BeGuru AI — Technical Docs: Runtime FastAPI, AgentOS, routers

Tóm lược

• FastAPI (src.api.main) là HTTP server: CORS, middleware logging, /health; các router freetext, workflows, interview, agents được include vào app.
• AgentOS (Agno) giữ registry agent; ProductManagerAgent và EngineerAgent (và các vai trò khác) gọi LLM qua OpenRouter (OpenRouterModel, attribution header mặc định theo docs).
• Luồng FE: POST /api/freetext/chat (SSE) → PM; POST /api/freetext/generate-code → Engineer ghi file dưới output_path. Luồng BE Go: init-go-project, backend-spec/*, generate-backend — có gate khóa spec trước khi sinh code.

Mục đích

Mô tả kiến trúc đang chạy của service beguru-ai ở mức triển khai; chi tiết request/response nằm trong docs/API_SPEC.md.

Sơ đồ tổng quan

Luồng chính: chat PM → generate-code (Next.js)

Luồng Go backend (tóm tắt)

Sau khi FE tồn tại, pipeline gồm khởi tạo module Go, dự thảo/ khóa BackendSpec, rồi generate-backend. Source of truth codegen: docs/backend-spec-*.yaml + docs/BACKEND_DESIGN.md sau bước write; có tích hợp excerpt FE ↔ BE qua frontend_output_path / backend_output_path — đủ chi tiết trong ARCHITECTURE_RUNTIME.md §2b.

Bảng thành phần (rút gọn)

Thành phần	Vai trò
FastAPI	HTTP, health, include routers
AgentOS	Registry / vòng đời agent
Settings	.env → projects_root_dir, model ids, ngưỡng freetext, …
OpenRouter	Gateway model; header attribution
Templates	guru-nextjs-template, beguru-go-template-be
StructuredLogger	Giới hạn độ dài log, preview LLM (Sprint 2)
Next static check	run_nextjs_static_check sau generate/edit (tuỳ cấu hình)

Triển khai điển hình

• Chạy: python scripts/run_agentos.py (uvicorn), thường systemd unit beguru-ai.
• Port: ví dụ 8089 (remote .env).
• Sync: rsync từ máy dev — xem scripts/deploy_to_server.sh.

Tham chiếu

• Repo beguru-ai: docs/ARCHITECTURE_RUNTIME.md, docs/API_SPEC.md.
• Tổng quan · Design & đĩa · Memory.

---