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, CORS, router
├── core/
│   ├── config.py          # ⚙️ Pydantic Settings (đọc .env)
│   └── database.py        # 🗄️ SQLAlchemy engine, session, Base
├── api/
│   └── courses.py         # 🌐 Route handlers (endpoints)
├── services/
│   ├── course_service.py  # 💼 Business logic (CRUD courses)
│   └── storage_service.py # 📦 R2/S3 presigned URL logic
├── models/
│   └── course.py          # 📋 SQLAlchemy ORM models
├── schemas/
│   └── course.py          # ✅ Pydantic request/response schemas
├── utils/
│   └── slugify.py         # 🔧 Utility functions
├── alembic/               # Alembic config
├── migrations/            # Migration files (auto-generated)
├── requirements.txt       # Python dependencies
├── Dockerfile             # Docker build config
├── .env                   # Local env vars (không commit)
└── .env.example           # Template env vars

Data Flow¶

graph TD
    A["Client Request"] --> B["api/courses.py<br/>(Route Handler)"]
    B --> C["services/course_service.py<br/>(Business Logic)"]
    C --> D["models/course.py<br/>(SQLAlchemy Model)"]
    D --> E["core/database.py<br/>(DB Session)"]
    E --> F["PostgreSQL"]
    B --> G["schemas/course.py<br/>(Validation)"]
    B --> H["services/storage_service.py<br/>(R2 Upload)"]
    H --> I["Cloudflare R2"]

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`