Kiến trúc và trạng thái hệ thống

Loại chính: Explanation
Đối tượng: developer, reviewer và operator
Kiểm chứng: 2026-08-14

Hệ thống có hai luồng độc lập gặp nhau tại Qdrant: ingestion chạy offline để biến PDF thành corpus; request path chạy online để hiểu câu hỏi, truy hồi bằng chứng, tạo câu trả lời và kiểm tra grounding.

Offline
PDF -> extract/repair -> monograph -> quarantine table/formula
    -> chunk schema v4 -> embedding -> Qdrant + manifest

Online
Browser -> Next.js BFF -> FastAPI RAG
        -> understand/guard -> Qdrant retrieval -> answer/validate
        -> PostgreSQL trace + conversation + feedback

Thành phần trên request path

apps/web cung cấp Next.js UI và BFF /api/chat.
BFF gọi POST /v1/rag/query, chuyển đổi DTO và map reason code cho UI.
apps/ai-service gắn correlation/trace context và điều phối RAG.
Qdrant giữ vector cùng payload provenance của chunk.
PostgreSQL giữ retrieval trace, conversation turn và feedback.
AWS Bedrock cung cấp query embedding; generation và rerank chỉ chạy khi bật.

Các service api-gateway, auth-service, user-service và chat-service là scaffold, chưa nằm trên live request path hiện tại.

Bản đồ repository

Đường dẫn	Trách nhiệm
`apps/web`	UI và BFF Next.js
`apps/ai-service`	FastAPI, RAG orchestration, adapters, migrations, evals
`ingestion/ingestion`	PDF extraction, quality gates, chunking và load
`ingestion/data`	dữ liệu raw/processed và artifact
`packages/*`	shared types, API client và UI dùng chung
`infra/docker`	local Compose và observability
`infra/helm`, `infra/argocd`	target Kubernetes/GitOps
`.github/workflows`	CI, deploy, rollback và Qdrant migration
`docs`	bộ tài liệu chuẩn
`docs-legacy`	raw/legacy để tra lịch sử

Trạng thái triển khai

Thành phần	Trạng thái được xác nhận
Web/BFF	có code, được lint và build trong CI
FastAPI RAG	có code và test tự động
PDF → chunk schema v4	có code, quality gate và test
Qdrant manifest gate	runtime bắt buộc khi embedding bật
PostgreSQL trace/hội thoại/feedback	có migration và adapter
Bedrock Cohere embedding	production provider được runtime hỗ trợ
Answer generation	tùy chọn; mặc định tắt
Prometheus/Tempo/Grafana	có cấu hình local và production
EC2 Compose + Caddy	luồng deploy hiện hành trong GitHub Actions
Helm + ArgoCD	có manifest; chưa đủ bằng chứng để khẳng định đang phục vụ production
Frontend automated tests	chưa có test runner; CI chỉ lint/build
`visual-diff`, `scaffold-golden`	CLI tồn tại nhưng chưa triển khai

Mô hình triển khai

Local thường chạy PostgreSQL, Qdrant và observability bằng Compose; web và ai-service chạy trực tiếp trên host. Các app service trong Compose local đang bị comment nên docker compose up không tự tạo toàn bộ ứng dụng.

Production hiện hành được workflow mô tả là EC2 + Docker Compose + Caddy. CI và deploy là hai workflow độc lập; operator phải chủ động áp gate CI xanh và xác nhận SHA, health cùng synthetic query sau deploy.

Helm/ArgoCD là target platform có implementation trong Git. “Manifest render được” không đồng nghĩa “cluster đang phục vụ traffic”; cần xác nhận cluster, secret, image tag, ingress, health và rollback thực tế trước khi đổi trạng thái.

Biên an toàn kiến trúc

Mỗi evidence phải có provenance về trang in và chunk. Generator không tự quyết claim hợp lệ: code kiểm tra citation, số liệu, entailment và completeness. Khi không chứng minh được, hệ thống trả clarify, verify_pdf hoặc abstain.

4.0 KiB Raw Blame History