docs/proposal/08_project_structure.md

Cấu trúc Dự án & Tổ chức Mã nguồn

Tài liệu này đặc tả cách tổ chức thư mục và quy chuẩn viết mã. Manim chỉ được khởi chạy trong worker, trong môi trường Docker (image cố định phiên bản); backend API không embed Manim runtime.

---

1. Cấu trúc Thư mục Tổng thể (Project Tree)

Cây dưới đây khớp skeleton repo (file .gitkeep giữ thư mục rỗng trong Git). Các file main.py, tasks.py, v.v. sẽ được thêm khi triển khai code.

Manim_Agent/
├── backend/                # FastAPI (không chạy Manim)
│   ├── api/
│   ├── core/
│   ├── db/
│   └── main.py             # (sẽ thêm) entrypoint API
├── worker/                 # Consumer job render — Manim/FFmpeg **trong Docker**
│   ├── environment/        # Dockerfile, requirements image render
│   ├── tasks.py            # (sẽ thêm) dequeue / gọi docker run
│   └── renderer.py         # (sẽ thêm) chuẩn bị volume, log, upload
├── ai_engine/
│   ├── agents/
│   ├── config/
│   │   └── agent_models.example.yaml  # model/temperature theo agent; copy → agent_models.yaml
│   ├── prompts/
│   └── llm_client.py       # (sẽ thêm) LiteLLM wrapper — đọc config ở trên
├── primitives/             # Helper Manim — mount/copy vào image worker khi build
├── shared/
│   └── schemas/            # Pydantic / contract dùng chung API ↔ worker
├── output/                 # Artefact cục bộ khi dev (không commit video lớn)
├── tests/                  # Pytest: unit → integration → e2e (gate cuối: LLM thật)
│   ├── unit/
│   ├── integration/
│   └── e2e/                # Full pipeline + LLM API thực (chỉ chạy khi có secret / CI release)
├── docs/
│   ├── proposal.md
│   └── proposal/
└── requirements.txt        # (sẽ thêm) dependency backend/ai; image Docker tách file riêng

---

2. Phân vai runtime

Vị trí	Manim	Docker
backend/	Không	Không (chỉ orchestration)
worker/	Có (CLI / Python)	Có — container là môi trường render chuẩn
ai_engine/	Không	Không

---

3. Tổ chức Mã nguồn Manim (Function-based)

Để tránh file sinh ra quá dài, áp dụng Part-based Scene (ví dụ minh họa — sẽ nằm trong artefact scene do Builder sinh):

from primitives import *

class TechnicalScene(Scene):
    def construct(self):
        self.setup_environment()
        self.step_1_introduction()
        self.step_2_explanation()
        self.step_3_conclusion()

    def setup_environment(self):
        pass

    def step_1_introduction(self):
        title = get_text_panel("Tìm kiếm nhị phân")
        self.play(Write(title))
        self.wait(2.5)

    def step_2_explanation(self):
        pass

• Mỗi step_n ánh xạ tới nhóm segment trên timeline (xem 05_pipeline.md).
• Worker mount thư mục job (code + asset), chạy image, ghi output/.

---

4. Cấu trúc Lưu trữ (Cloud Storage)

• **audio/:** {project_id}/{scene_id}.mp3, {project_id}/{scene_id}_timestamps.json
• **videos/:** {project_id}/previews/, {project_id}/final/
• **assets/:** logo, ảnh người dùng

---

Trở về tập chỉ mục: 00_index.md