BeGuru AI — Technical Docs: Tổng quan kiến trúc (runtime, agent, đĩa)

Tóm lược

• BeGuru AI (service beguru-ai) là backend FastAPI gắn AgentOS (Agno); các route /api/freetext/*, /api/workflows/*, … điều phối PM và Engineer gọi LLM qua OpenRouter, ghi kết quả xuống projects_root_dir (Next.js / Go) cùng cây design-system/ trong mỗi project FE.
• Tài liệu gốc (SSOT) trong repo: docs/ARCHITECTURE_RUNTIME.md, docs/MEMORY_AND_CONTEXT_LAYERS.md, docs/API_SPEC.md.
• Thứ tự đọc đề xuất: bài này (map) → Design & đĩa → Runtime → Memory → Mem0 & cross-session → Technical Narrative (mental model & SSOT tóm tắt) → AIO Sandbox (thực thi cô lập — lộ trình).

Hiện trạng vs hướng đi (North Star)

Hiện tại hệ chạy theo request–response / SSE: client gửi messages, server nén context (ContextCompressor), ghim pins, Engineer ghi file + (tuỳ flow) kiểm tra tĩnh — chưa có graph điều phối đa bước bắt buộc hay sandbox chạy lệnh thống nhất giữa mọi route.

Hướng sản phẩm (đối chiếu các assistant dạng Claude Code): autonomous coding cần vòng lặp Plan → sửa/ghi đĩa → chạy lệnh trong môi trường cách ly → quan sát stdout/exit → checkpoint, có thể đa agent (PM, Engineer FE, Engineer BE) với handoff có contract (spec, BUILD_STATE, API). Kiến trúc tham chiếu trong ecosystem thường dùng LangGraph (hoặc tương đương) cho state + routing có điều kiện + checkpoint; ví dụ case study production với 8 agent, orchestrator–worker, sandbox modal, middleware và caching — xem FRE|Nxt × InterviewLM — LangGraph multi-agent (bài ngoài, không phải BeGuru).

BeGuru không cam kết đã triển khai đủ các lớp đó; bài Mem0 & cross-session mô tả một mảnh lộ trình (memory ngữ nghĩa + Qdrant). Khi spike, nên đo latency, chi phí, an toàn sandbox trước khi gắn vào API công khai.

Kiến trúc mục tiêu

Artifact-first: file .guru/ / design-system vẫn là nguồn chân lý; nhớ ngữ nghĩa là lớp bổ sung. Về memory, BeGuru vận hành song song ba mặt: (1) short-term trong phiên (RawHistory → ContextCompressor → PinnedLayer), (2) artifact bền trên đĩa (templates, BUILD_STATE, MASTER), và (3) semantic long-term (MemoryPlane → mem0 → vector store). Hover vào ô để thấy luồng dữ liệu; dùng nút mở rộng để xem sơ đồ toàn màn.

Chú thích màu ô (kind): client / router (xanh dương) · api (tím) · agent (hồng) · llm (amber) · disk / template (xanh lá / cam) · memory (đỏ nhạt) · sandbox (cyan) · obs (xám).

See also: Memory & context layers · Mem0 & cross-session

React Agent loop — orchestrator, sandbox & observe

Autonomous coding cần vòng phản hồi: orchestrator giữ state/checkpoint, router chọn agent phù hợp (PM, FE, BE), agents gọi LLM để sinh nội dung rồi ghi artifact; artifact có thể chạy trong sandbox để quan sát stdout/exit — kết quả quan sát feed ngược về orchestrator để quyết định bước tiếp.

Tech stack đề xuất (mục tiêu lộ trình)

Lớp	Đề xuất	Vai trò ngắn
Điều phối đa bước	LangGraph (Python); Temporal khi cần durable / chờ người / SLA dài	State, conditional edges, checkpoint; hybrid LangGraph-inside-Temporal nếu cần
MemoryPlane	Interface nội bộ; backend đầu tiên mem0 (AsyncMemory)	retrieve / commit thống nhất cho PM + Engineer routes
Vector store	Qdrant (compose); tuỳ chọn pgvector nếu gom một Postgres	Semantic search memories; tenant qua collection / policy
Sandbox	E2B hoặc Docker + giới hạn CPU/time/network	Quan sát sau khi ghi đĩa — gần pattern case study modal sandbox
LLM	OpenRouter (giữ)	Tách model rẻ cho extract memory vs model mạnh cho codegen
Quan sát	Langfuse (đã có) + OpenTelemetry → Langfuse	Trace graph, tool, sandbox span
Agno	Giữ registry / MCP / agent class; có thể thu hẹp khi logic chuyển dần sang node graph	Không bắt buộc big-bang thay framework

*Temporal: tùy spike stack-spike (SLO, chi phí vận hành).

Hiện tại vs đề xuất (một bảng)

Lớp	Hiện tại (typical)	Đề xuất mục tiêu
Điều phối	Route FastAPI + stream trực tiếp	LangGraph (+ Temporal khi cần)
Nhớ xuyên phiên	Chưa / từng spike mem0	MemoryPlane → mem0 + Qdrant
Kiểm chứng tự động	Static check cục bộ trong flow	Sandbox Plane + vòng Observe
Quan sát	Logger + Langfuse tuỳ chọn	Langfuse + OTel end-to-end

Mục đích và phạm vi

Bài này không thay thế OpenAPI hay tài liệu nội bộ đầy đủ; nó cố định bối cảnh kiến trúc và chỗ các bộ phận gắn với nhau để đọc tiếp các bài chuyên sâu.

Sơ đồ tổng quan (runtime)

Sơ đồ SVG tương tác bên dưới: hover vào từng ô để highlight nhánh (cạnh và các ô liên quan). Các mã ngắn (ui, api, …) khớp với bảng đối chiếu ngay sau sơ đồ.

Đối chiếu nhanh (mã trên sơ đồ):

Mã	Thành phần
ui	Client (Web / Studio / CLI)
api	FastAPI — HTTP, CORS, logging
os	AgentOS Agno — cùng process với API
ft … ag	Các router REST (freetext, workflows, interview, agents)
pm, en, ar	Agent PM / Engineer / kiến trúc & QA
or	OpenRouter (gateway model)
proj, tpl, ds	Artifact trên đĩa (project, template, design-system)
lf, log	Langfuse (tuỳ chọn) và StructuredLogger

Bảng thành phần

Thành phần	Vai trò	Ghi chú / artifact	Bài liên quan
FastAPI	HTTP server, CORS, logging, /health	src.api.main	Runtime
AgentOS (Agno)	Registry agent, khởi tạo framework agent	Cùng process với API	Runtime
Routers	freetext, workflows, interview, agents	Include từ main.py	Runtime
PM Agent	Thảo luận spec, handoff LABEL_*, khối ## BEGURU_FE_SPEC / BE	Stream SSE	Runtime
Engineer Agent	generate-code, edit-code, generate-backend (Go)	Ghi file theo output_path	Runtime, Design & đĩa
OpenRouter	Gateway tới các model; attribution header (Referer / title)	Env model trong Settings	Runtime
Artifact đĩa	MASTER.md, BUILD_STATE.md, PRODUCT_PLAN.md, beguru_chat_context.json	Dưới design-system/ mỗi project	Design & đĩa
Context pipeline	Nén history, ghim pins, context pack cho Engineer	ContextCompressor, v.v.	Memory
SQLite (Agno)	Session / workflow / optional persist summary	data/agno.db (cấu hình tuỳ môi trường)	Memory
Memory xuyên phiên (lộ trình)	Facts theo user_id, semantic search	mem0 + Qdrant, inject ở route — xem bài Mem0	Mem0 & cross-session

Tech stack hiện tại (điển hình)

Lớp	Công nghệ
Runtime	Python, FastAPI, Uvicorn
Agents	Agno AgentOS, agents PM / Engineer / …
LLM	OpenRouter (model cấu hình qua .env / Settings)
Output FE	Template Next.js (templates/guru-nextjs-template), rule .guru/rules/
Output BE	Template Go (templates/beguru-go-template-be), pipeline init-go-project → backend-spec/* → generate-backend
Quan sát	StructuredLogger; Langfuse tuỳ chọn
Lộ trình	Xem mục Kiến trúc đề xuất và Tech stack đề xuất phía trên

Luồng sản phẩm chính (FE trước)

Luồng Go backend (sau FE, có gate backend-spec) được mô tả trong ARCHITECTURE_RUNTIME.md và bài Runtime.

Tham chiếu trong repo beguru-ai

• docs/ARCHITECTURE_RUNTIME.md — sơ đồ, bảng thành phần, deploy điển hình.
• docs/API_SPEC.md — contract HTTP, output_path, field request/response.
• docs/MEMORY_AND_CONTEXT_LAYERS.md — pipeline nén, pins, artifact.

---