Project Structure — Cấu trúc dự án¶

Monorepo chứa cả Backend, Frontend, và Documentation trong cùng một repository.

Tổng quan thư mục gốc¶

chienle-labs/
├── backend/              # FastAPI Backend (Python)
├── frontend/             # Next.js Frontend (TypeScript)
├── docs/                 # MkDocs documentation (bạn đang đọc)
├── mkdocs.yml            # MkDocs config
├── requirements-docs.txt # Dependencies cho docs
├── .gitignore
└── README.md

Backend (`backend/`)¶

Kiến trúc Layered Architecture — mỗi layer có trách nhiệm riêng biệt:

backend/
├── main.py               # 🚀 Entry point — FastAPI app
├── core/
│   ├── config.py          # ⚙️ Pydantic Settings (AI Keys, R2, DB)
│   └── database.py        # 🗄️ Connection pool
├── api/
│   ├── courses.py         # 🌐 Public course endpoints
│   └── admin.py           # 🔐 Admin endpoints (AI, CRUD, Media)
├── services/
│   ├── ai_service.py      # 🤖 AI Assistant (Gemini/OpenAI Logic)
│   ├── course_service.py  # 💼 Course & Roadmap logic
│   └── storage_service.py # 📦 R2/S3 integration
├── models/
│   ├── course.py          # 📋 Course & Roadmap models
│   └── lesson.py          # 📖 Lesson contents
├── schemas/
│   └── course.py          # ✅ Validation schemas
├── migrations/            # Version control cho DB
└── .env                   # Chứa API Keys nhạy cảm

Data Flow với AI Assistant¶

graph TD
    A["Admin UI (Frontend)"] -->|Prompt + Context| B["api/admin.py"]
    B -->|Instruction| C["services/ai_service.py"]
    C -->|Try Gemini| D["Google GenAI"]
    D -->|Quota Error| E["Fallback OpenAI"]
    E -->|Success| C
    C -->|Sanitized HTML| B
    B -->|Save| F["models/lesson.py"]

Frontend (`frontend/`)¶

Sử dụng Next.js App Router:

frontend/
├── app/
│   ├── layout.tsx         # 🏗️ Root layout (HTML, fonts, providers)
│   ├── page.tsx           # 🏠 Home page component
│   └── globals.css        # 🎨 Global styles (Tailwind)
├── lib/
│   └── api.ts             # 📡 API client (fetch wrapper)
├── next.config.js         # Next.js configuration
├── tailwind.config.ts     # Tailwind CSS config
├── tsconfig.json          # TypeScript config
├── package.json           # Node dependencies
├── .env.local             # Local env vars
└── .env.example           # Template

Docs (`docs/`)¶

Tài liệu bạn đang đọc — build bằng MkDocs Material:

docs/
├── index.md                        # Home page
├── getting-started/                # Onboarding
├── backend/                        # Backend docs
├── frontend/                       # Frontend docs
├── git-flow/                       # Branching & environments
├── deployment/                     # Deploy guides
└── references/                     # BA & Delivery docs

Quy tắc đặt tên¶

Layer	Convention	Ví dụ
Files	`snake_case.py` / `kebab-case.ts`	`course_service.py`, `api.ts`
Classes	`PascalCase`	`CourseCreate`, `StorageService`
Functions	`snake_case`	`create_course()`, `get_db()`
Database	`snake_case` (plural table)	`courses` table
API Routes	`kebab-case`	`/courses/{id}/upload-url`