Skip to content

Commit 6b3ee02

Browse files
h7mlh7ml
committed
docs: 添加组合模式文档并更新入门指南
新增内容: - 新增 guide/combinations.md (中文) - 组合模式使用指南 - 新增 en/guide/combinations.md (英文) - Combinations guide 更新内容: - 更新 guide/getting-started.md - 完善快速开始指南 - 更新 guide/index.md - 优化指南索引 - 更新 index.md - 更新首页内容 - 更新 en/* 对应英文文档 - 更新 .vitepress/sidebar.ts - 添加新文档到侧边栏 修改文件: - .vitepress/sidebar.ts - guide/combinations.md (新增) - guide/getting-started.md - guide/index.md - index.md - en/guide/combinations.md (新增) - en/guide/getting-started.md - en/guide/index.md - en/index.md
1 parent 110f1ce commit 6b3ee02

9 files changed

Lines changed: 745 additions & 19 deletions

File tree

‎.vitepress/sidebar.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ const zhGuideSidebar: DefaultTheme.SidebarItem[] = [
88
items: [
99
{ text: '简介', link: '/guide/' },
1010
{ text: '快速开始', link: '/guide/getting-started' },
11+
{ text: '🔀 架构组合指南', link: '/guide/combinations' },
1112
],
1213
},
1314
{
@@ -99,6 +100,7 @@ const enGuideSidebar: DefaultTheme.SidebarItem[] = [
99100
items: [
100101
{ text: 'Introduction', link: '/en/guide/' },
101102
{ text: 'Quick Start', link: '/en/guide/getting-started' },
103+
{ text: '🔀 Architecture Combinations', link: '/en/guide/combinations' },
102104
],
103105
},
104106
{

‎en/guide/combinations.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Architecture Combination Guide
2+
3+
The core advantage of HaloLight lies in **complete frontend-backend decoupling**, supporting any combination. This document helps you choose the most suitable tech stack combination.
4+
5+
## 🎯 Quick Decision Flowchart
6+
7+
```mermaid
8+
graph TD
9+
A[Start Selection] --> B{Team Size?}
10+
B -->|Small <5| C{SEO Required?}
11+
B -->|Medium 5-20| D{Tech Preference?}
12+
B -->|Large >20| E[Angular + Spring Boot]
13+
14+
C -->|Yes| F[Nuxt + FastAPI]
15+
C -->|No| G[Vue + FastAPI]
16+
17+
D -->|Node.js| H[Next.js + NestJS]
18+
D -->|Python| I[Vue + FastAPI]
19+
D -->|Java| J[Angular + Spring Boot]
20+
D -->|Go| K[SvelteKit + Go Fiber]
21+
```
22+
23+
## 📊 Combination Evaluation Matrix
24+
25+
Rating mainstream combinations across dimensions (max ⭐⭐⭐⭐⭐):
26+
27+
### Next.js + NestJS
28+
29+
| Dimension | Rating | Description |
30+
|-----------|--------|-------------|
31+
| Development Efficiency | ⭐⭐⭐⭐⭐ | TypeScript full-stack unification, type sharing |
32+
| Performance | ⭐⭐⭐⭐ | SSR + edge caching optimization |
33+
| Learning Curve | ⭐⭐⭐ | Need to understand React and NestJS architecture |
34+
| Ecosystem Maturity | ⭐⭐⭐⭐⭐ | npm ecosystem extremely rich |
35+
| Deployment | ⭐⭐⭐⭐ | Vercel + Railway/Fly.io one-click deploy |
36+
| **Overall** | **⭐⭐⭐⭐** | First choice for multi-tenant SaaS, enterprise backends |
37+
38+
### Vue + FastAPI
39+
40+
| Dimension | Rating | Description |
41+
|-----------|--------|-------------|
42+
| Development Efficiency | ⭐⭐⭐⭐⭐ | Vue smooth learning curve, FastAPI fast dev |
43+
| Performance | ⭐⭐⭐⭐ | Vue 3 compilation optimized, Python async efficient |
44+
| Learning Curve | ⭐⭐⭐⭐⭐ | Both relatively easy to pick up |
45+
| Data Processing | ⭐⭐⭐⭐⭐ | Python data science ecosystem unbeatable |
46+
| Deployment | ⭐⭐⭐⭐ | Frontend CDN, backend containerized |
47+
| **Overall** | **⭐⭐⭐⭐⭐** | First choice for data/AI-driven apps |
48+
49+
### Angular + Spring Boot
50+
51+
| Dimension | Rating | Description |
52+
|-----------|--------|-------------|
53+
| Development Efficiency | ⭐⭐⭐ | Rigorous architecture, high initial investment |
54+
| Performance | ⭐⭐⭐⭐ | Enterprise optimization mature |
55+
| Learning Curve | ⭐⭐ | Both have some complexity |
56+
| Enterprise Maturity | ⭐⭐⭐⭐⭐ | Large enterprise first choice |
57+
| Long-term Maintenance | ⭐⭐⭐⭐⭐ | Clear architecture, highly maintainable |
58+
| **Overall** | **⭐⭐⭐⭐** | Best for large enterprises, long-term projects |
59+
60+
### SvelteKit + Go Fiber
61+
62+
| Dimension | Rating | Description |
63+
|-----------|--------|-------------|
64+
| Development Efficiency | ⭐⭐⭐⭐ | Concise code, great dev experience |
65+
| Performance | ⭐⭐⭐⭐⭐ | Both are performance benchmarks |
66+
| Learning Curve | ⭐⭐⭐ | Svelte unique syntax, need to learn Go |
67+
| Resource Usage | ⭐⭐⭐⭐⭐ | Extremely low memory and CPU usage |
68+
| Deployment | ⭐⭐⭐⭐⭐ | Tiny container images, edge deployment ready |
69+
| **Overall** | **⭐⭐⭐⭐⭐** | Best for high-performance real-time apps |
70+
71+
## 🎨 Combination Matrix
72+
73+
Below shows all possible frontend-backend combinations. Each cell represents a viable tech stack pairing.
74+
75+
### Frontend Frameworks (Horizontal) × Backend APIs (Vertical)
76+
77+
| Frontend \ Backend | NestJS | Node.js | FastAPI | Spring Boot | Go | PHP | Bun | tRPC BFF |
78+
|--------------------|--------|---------|---------|-------------|----|----|-----|----------|
79+
| **Next.js** | ⭐ Best | ✅ | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ⭐ Best |
80+
| **Nuxt** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭐ Best |
81+
| **Vue** | ✅ | ✅ | ⭐ Best | ✅ | ✅ | ✅ | ✅ | ✅ |
82+
| **Angular** | ✅ | ✅ | ✅ | ⭐ Best | ⭐ Best | ✅ | ✅ | ✅ |
83+
| **SvelteKit** | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ✅ | ✅ | ✅ |
84+
| **Astro** | ✅ | ✅ | ⭐ Best | ✅ | ✅ | ✅ | ✅ | ✅ |
85+
| **Solid.js** | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ✅ | ⭐ Best | ✅ |
86+
| **Qwik** | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ✅ | ⭐ Best | ✅ |
87+
| **Remix** | ⭐ Best | ⭐ Best | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ⭐ Best |
88+
| **Preact** | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ✅ | ⭐ Best | ✅ |
89+
| **Lit** | ✅ | ✅ | ✅ | ✅ | ✅ | ⭐ Best | ✅ | ✅ |
90+
91+
**Legend**:
92+
- ⭐ Best: Significant advantages in specific scenarios
93+
- ✅ Available: Fully compatible, ready to use
94+
95+
## 💡 Selection Recommendations
96+
97+
### By Team Size
98+
99+
#### Small Teams (< 5 people)
100+
- **Vue + FastAPI** - Quick to learn, high efficiency
101+
- **Preact + Bun** - Lightweight, good performance
102+
- **Astro + Node.js** - Content-focused scenarios
103+
104+
#### Medium Teams (5-20 people)
105+
- **Next.js + NestJS** - TypeScript unified stack
106+
- **Vue + Spring Boot** - Balance usability and enterprise features
107+
- **SvelteKit + FastAPI** - Balance performance and efficiency
108+
109+
#### Large Teams (> 20 people)
110+
- **Angular + Spring Boot** - Architectural standards, maintainability
111+
- **Next.js + NestJS + tRPC BFF** - Micro-frontend + BFF architecture
112+
- **Any Frontend + GraphQL Gateway + Microservices**
113+
114+
### By Tech Stack Preference
115+
116+
#### TypeScript Full-Stack
117+
- Next.js / Nuxt / Remix + NestJS + tRPC BFF
118+
- Solid.js / Qwik + Bun + Hono
119+
120+
#### Python Ecosystem
121+
- Vue / React / Astro + FastAPI
122+
- SvelteKit + FastAPI
123+
124+
#### Java Ecosystem
125+
- Angular / Vue + Spring Boot
126+
127+
#### Go Ecosystem
128+
- SvelteKit / Solid / Qwik + Go Fiber
129+
130+
### By Deployment Environment
131+
132+
#### Serverless / Edge-First
133+
- Next.js + NestJS (Vercel + Vercel Functions)
134+
- Nuxt + Bun (Cloudflare Workers)
135+
- Astro + Deno Deploy
136+
137+
#### Traditional Servers
138+
- Any Frontend (Nginx static hosting) + Any Backend (PM2/Systemd)
139+
140+
#### Containerized (Kubernetes)
141+
- Any Combination (Docker images + K8s Deployment)
142+
143+
#### Hybrid Cloud
144+
- Frontend (CDN) + Backend (Private Cloud) + tRPC BFF (Edge nodes)
145+
146+
## 🔧 Tech Stack Comparison
147+
148+
### Frontend Framework Features
149+
150+
| Feature | Next.js | Vue | Angular | SvelteKit | Solid | Qwik |
151+
|---------|---------|-----|---------|-----------|-------|------|
152+
| **Learning Curve** | Medium | Low | High | Low | Medium | Medium |
153+
| **TypeScript** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
154+
| **SSR/SSG** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
155+
| **Performance** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
156+
| **Ecosystem** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
157+
| **Bundle Size** | Medium | Small | Large | Minimal | Minimal | Small |
158+
159+
### Backend Tech Features
160+
161+
| Feature | NestJS | FastAPI | Spring Boot | Go Fiber |
162+
|---------|--------|---------|-------------|----------|
163+
| **Dev Efficiency** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
164+
| **Performance** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
165+
| **TypeScript** | ⭐⭐⭐⭐⭐ | - | - | - |
166+
| **Enterprise Maturity** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
167+
| **Data Science** | ⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐ |
168+
| **Resource Usage** | Medium | Small | Large | Minimal |
169+
170+
## 🚀 Quick Setup
171+
172+
After choosing your combination, follow these steps:
173+
174+
### Step 1: Start Frontend
175+
176+
```bash
177+
# Example with Vue
178+
git clone https://github.com/halolight/halolight-vue.git
179+
cd halolight-vue
180+
pnpm install
181+
pnpm dev
182+
```
183+
184+
### Step 2: Start Backend API
185+
186+
```bash
187+
# Example with FastAPI
188+
git clone https://github.com/halolight/halolight-api-python.git
189+
cd halolight-api-python
190+
pip install -e ".[dev]"
191+
uvicorn app.main:app --reload
192+
```
193+
194+
### Step 3: Configure Frontend to Connect Backend
195+
196+
```bash
197+
# Frontend project's .env.local
198+
VITE_API_URL=http://localhost:8000/api
199+
VITE_USE_MOCK=false # Disable Mock, use real API
200+
```
201+
202+
---
203+
204+
## 📚 Related Documentation
205+
206+
- [Architecture Overview](/en/development/architecture) - Deep dive into frontend-backend separation design
207+
- [API Design Specification](/en/development/api-patterns) - Interface contract explanation
208+
- [Authentication System](/en/development/authentication) - Unified authentication mechanism
209+
- [Permission Management](/en/development/components#permission-control) - RBAC implementation

‎en/guide/getting-started.md‎

Lines changed: 129 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,97 @@
1-
# Quick Start
1+
# Getting Started
22

3-
Choose your preferred framework version to quickly start HaloLight.
3+
Choose your preferred frontend framework and match it with a backend API to quickly start with HaloLight.
4+
5+
## 🎯 Choose Your Combination
6+
7+
HaloLight uses a **fully decoupled frontend-backend architecture**, supporting **11 Frontends × 8 Backends = 88 Combinations**.
8+
9+
### Step 1: Choose Frontend Framework (Pick 1 of 11)
10+
11+
| Framework | Use Cases | Characteristics |
12+
|-----------|-----------|-----------------|
13+
| **Next.js / Nuxt** | Multi-tenant SaaS, SEO needs | SSR + Edge rendering friendly |
14+
| **Vue** | Quick delivery for small-medium teams | Lightweight, smooth learning curve |
15+
| **Angular** | Large-scale, long-term projects | Strong typing, clear architecture |
16+
| **SvelteKit / Solid / Qwik** | High interaction, real-time scenarios | Ultimate performance & reactivity |
17+
| **Remix / Preact / Lit** | Progressive enhancement, lightweight | Web Components, small bundle size |
18+
| **Astro** | Content-focused admin panels | Islands architecture, zero JS by default |
19+
20+
### Step 2: Choose Backend API (Pick 1 of 8)
21+
22+
| Backend Tech | Use Cases | Characteristics |
23+
|--------------|-----------|-----------------|
24+
| **NestJS / Express** | Node.js ecosystem teams | High compatibility with frontend TS |
25+
| **FastAPI** | Data/AI-driven applications | Python ecosystem, rapid iteration |
26+
| **Spring Boot** | Enterprise, financial industry | Mature middleware ecosystem |
27+
| **Go Fiber** | High performance, high concurrency | Low resource usage |
28+
| **PHP Laravel** | Traditional web teams | Complete ecosystem, easy to learn |
29+
| **Bun + Hono** | Ultimate performance pursuit | Next-gen runtime |
30+
| **tRPC BFF** | Mobile/Desktop multi-platform | Type sharing, aggregation & simplification |
31+
32+
### Step 3: Recommended Combinations (By Scenario)
33+
34+
<details>
35+
<summary><b>📊 Multi-tenant SaaS / Enterprise Admin</b></summary>
36+
37+
**Recommended**: Next.js + NestJS
38+
39+
**Advantages**:
40+
- SSR + TypeScript end-to-end unification
41+
- Code sharing (types, utilities)
42+
- Mature deployment ecosystem (Vercel + Railway/Fly.io)
43+
44+
</details>
45+
46+
<details>
47+
<summary><b>🤖 Data-Intensive / AI-Driven Apps</b></summary>
48+
49+
**Recommended**: Vue + FastAPI or React + FastAPI
50+
51+
**Advantages**:
52+
- Python data science ecosystem (Pandas, NumPy, scikit-learn)
53+
- Fast API development (auto docs, dependency injection)
54+
- Lightweight frontend, easy chart library integration
55+
56+
</details>
57+
58+
<details>
59+
<summary><b>🏢 Large Enterprise / Long-term Projects</b></summary>
60+
61+
**Recommended**: Angular + Spring Boot
62+
63+
**Advantages**:
64+
- Strong typing, modular architecture
65+
- Mature enterprise middleware (auth, cache, message queue)
66+
- Long-term support and stability
67+
68+
</details>
69+
70+
<details>
71+
<summary><b>⚡ High-Performance Real-time Apps</b></summary>
72+
73+
**Recommended**: SvelteKit + Go Fiber
74+
75+
**Advantages**:
76+
- Frontend compilation optimization, minimal bundle
77+
- Backend high throughput, low latency
78+
- Low resource usage, cost optimization
79+
80+
</details>
81+
82+
<details>
83+
<summary><b>📱 Mobile/Desktop Multi-platform Unified</b></summary>
84+
85+
**Recommended**: Any Frontend + tRPC BFF + Any Backend
86+
87+
**Advantages**:
88+
- BFF aggregates and tailors APIs for multiple platforms
89+
- TypeScript end-to-end type safety
90+
- Reduces frontend complexity
91+
92+
</details>
93+
94+
---
495

596
## Requirements
697

@@ -71,8 +162,43 @@ project-root/
71162
└── package.json
72163
```
73164

165+
## 🚀 Quick Examples
166+
167+
### Option 1: Next.js + NestJS
168+
169+
```bash
170+
# Terminal 1: Start frontend
171+
git clone https://github.com/halolight/halolight.git && cd halolight
172+
pnpm install && pnpm dev
173+
```
174+
175+
```bash
176+
# Terminal 2: Start backend
177+
git clone https://github.com/halolight/halolight-api-nestjs.git && cd halolight-api-nestjs
178+
pnpm install && pnpm dev
179+
```
180+
181+
### Option 2: Vue + FastAPI
182+
183+
```bash
184+
# Terminal 1: Start frontend
185+
git clone https://github.com/halolight/halolight-vue.git && cd halolight-vue
186+
pnpm install && pnpm dev
187+
```
188+
189+
```bash
190+
# Terminal 2: Start backend
191+
git clone https://github.com/halolight/halolight-api-python.git && cd halolight-api-python
192+
pip install -e ".[dev]" && uvicorn app.main:app --reload
193+
```
194+
195+
---
196+
74197
## Next Steps
75198

76199
- [Next.js Version](/en/guide/nextjs) - Deep dive into Next.js implementation
77200
- [Vue Version](/en/guide/vue) - Deep dive into Vue implementation
78-
- [Development Docs](/en/development/) - View design specifications
201+
- [NestJS API](/en/guide/api-nestjs) - NestJS backend development guide
202+
- [Python API](/en/guide/api-python) - FastAPI backend development guide
203+
- [Architecture Combinations](/en/guide/combinations) - View all 88 combinations
204+
- [Development Docs](/en/development/) - View design specifications and contracts

0 commit comments

Comments
 (0)