# Catalog tài liệu dự án

## Phân loại

**Loại tài liệu:** Reference.

**Reader job:** tìm nhanh tài liệu đúng cho một vai trò hoặc câu hỏi.

## Theo nhu cầu

| Tôi muốn… | Bắt đầu tại |
|---|---|
| Hiểu toàn bộ PDF → chatbot | [`pipeline-tu-pdf-den-chatbot-production.md`](../pipeline-tu-pdf-den-chatbot-production.md) |
| Chạy một query và theo citation | [`tutorials/first-grounded-query.md`](../tutorials/first-grounded-query.md) |
| Setup môi trường local | [`23-local-development.md`](../23-local-development.md) |
| Rebuild và publish corpus | [`how-to/rebuild-and-publish-corpus.md`](../how-to/rebuild-and-publish-corpus.md) |
| Chạy test/eval | [`how-to/run-tests-and-evals.md`](../how-to/run-tests-and-evals.md) |
| Deploy hoặc rollback | [`how-to/deploy-and-rollback.md`](../how-to/deploy-and-rollback.md) |
| Điều tra một request | [`how-to/trace-a-request.md`](../how-to/trace-a-request.md) |
| Tra API | [`12-api-architecture.md`](../12-api-architecture.md) |
| Tra biến môi trường | [`15-configuration.md`](../15-configuration.md) |
| Tra reason code | [`29-glossary.md`](../29-glossary.md) |
| Xử lý sự cố | [`25-troubleshooting.md`](../25-troubleshooting.md) |
| Hiểu vì sao không dùng dense-only | [`explanation/why-structured-rag.md`](../explanation/why-structured-rag.md) |
| Xem giới hạn thật | [`26-known-limitations.md`](../26-known-limitations.md) |

## Theo vai trò

| Vai trò | Lộ trình đọc |
|---|---|
| Contributor mới | Tutorial → `01` repository → `23` local → `18` testing |
| AI/RAG engineer | `08` understanding → `09` retrieval → `10` orchestration → `11` grounding → `19` eval |
| Ingestion engineer | `04` ingestion → `05` parsing → `06` chunking → `07` indexing |
| Backend engineer | `12` API → `14` stores → `15` config → `17` observability |
| Frontend engineer | `13` frontend → `12` API → `16` security |
| Operator/SRE | Deploy how-to → trace how-to → `24` operations → `25` troubleshooting |
| Reviewer/mentor | Canonical pipeline → showcase plan → `26` limitations → `27` debt |

## Bộ tài liệu `00–29`

| File | Loại chính | Nội dung |
|---|---|---|
| `00` | Explanation | Tổng quan sản phẩm và ranh giới |
| `01` | Reference | Cấu trúc repository |
| `02` | Explanation | Kiến trúc runtime |
| `03` | Explanation | Data flow offline và online |
| `04` | Explanation | Ingestion pipeline |
| `05` | Explanation | PDF parsing |
| `06` | Reference | Document model và chunk schema |
| `07` | Reference | Qdrant, manifest và storage |
| `08` | Explanation | Query understanding |
| `09` | Explanation | Retrieval routes |
| `10` | Explanation | RAG orchestration |
| `11` | Explanation | Generation và grounding |
| `12` | Reference | API contracts |
| `13` | Explanation | Frontend architecture |
| `14` | Reference | Datastores |
| `15` | Reference | Configuration |
| `16` | Explanation | Security model và gaps |
| `17` | Reference | Metrics, traces và correlation |
| `18` | Reference | Test inventory và commands |
| `19` | Explanation | Evaluation assets và gaps |
| `20` | Explanation | Deployment topology |
| `21` | Explanation | Kubernetes/ArgoCD target state |
| `22` | Explanation | CI/CD design và consequences |
| `23` | How-to | Local development |
| `24` | How-to | Production operations |
| `25` | How-to | Troubleshooting |
| `26` | Reference | Known limitations |
| `27` | Explanation | Technical debt |
| `28` | Explanation | Roadmap derived from code |
| `29` | Reference | Glossary và reason codes |

## Nguồn sự thật

Thứ tự ưu tiên khi có mâu thuẫn:

1. Runtime code.
2. Runtime configuration và workflow.
3. Tests.
4. Migrations và deployment manifests.
5. Tài liệu hiện hành.
6. ADR, progress log và handoff lịch sử.