Documentation Improvement Summary¶

Laporan reorganisasi dokumentasi — 2026-05-25.

Yang dilakukan¶

1. Struktur folder baru di `docs/`¶

Dibuat 16 kategori: architecture, migration, backend, flutter, monitoring, kafka, clickhouse, postgresql, api, flows, infrastructure, deployment, runbooks, troubleshooting, glossary, decisions, references.

2. Halaman monitoring proyek (permintaan 2026-05-25)¶

File	Status
`project-dashboard.md`	✅ Ringkasan 1 halaman — traffic light, jalur kritis, risiko
`project-todo-global.md`	✅ TODO agregasi 1–2 halaman — P0, gate cutover, indeks
`docs/TODO.md`	✅ Workstream dokumentasi
`runbooks/cutover-big-bang-TODO.md`	⏳ Placeholder runbook cutover

3. Dokumen fondasi baru¶

File	Status
`architecture/architecture-overview.md`	✅ Dibuat
`architecture/service-dependencies.md`	✅ Dibuat
`flows/event-flow.md`	✅ Dibuat
`migration/migration-status.md`	✅ Dibuat
`migration/legacy-to-modern-mapping.md`	✅ Dibuat
`glossary/glossary.md`	✅ Dibuat (ringkas + link ke 02)
`glossary/naming-conventions.md`	✅ Dibuat
`kafka/kafka-topics.md`	✅ Dibuat
`clickhouse/clickhouse-patterns.md`	✅ Dibuat
`monitoring/monitoring-flow.md`	✅ Dibuat
`deployment/deployment-overview.md`	✅ Dibuat

3. Indeks & navigasi¶

README.md — hub utama dengan jalur onboarding per peran
README per subfolder + cross-link ke sumber kanonik di database/, backend/, frontend/
references/source-of-truth-index.md
decisions/README.md — ADR ringkas

4. Troubleshooting awal¶

troubleshooting/cdc-lag.md
troubleshooting/cdc-consumer-errors.md
troubleshooting/tenant-search-path.md

5. Placeholder TODO¶

api/TODO.md, postgresql/TODO.md, infrastructure/TODO.md

6. Prinsip preservasi¶

Seri dokumen 00–15 tidak dipindah — referensi Git/RAG/tim tetap valid
RUNBOOK & TODO di folder implementasi tetap kanonik — docs/runbooks/ hanya indeks
Tidak ada logika bisnis yang diarang — semua klaim merujuk kode/dokumen existing

Duplikasi yang dirapikan (bukan dihapus)¶

Sebelum	Setelah
Arsitektur CDC di README cdc + AGENTS + CHECKLIST	Satu narasi di `flows/event-flow.md` + link
Konvensi di 07 + database/02	`glossary/naming-conventions.md` mengagregasi
Status migrasi di TODO.md + database/TODO	`migration/migration-status.md` sintesis
Glosarium 02 + istilah CDC	`glossary/glossary.md` + link ke 02

Informasi yang masih kurang¶

Topik	Prioritas	Catatan
OpenAPI final & error contract	Tinggi	Blocking Flutter operasional
Indeks trigger/fungsi per tabel	Tinggi	Hanya tersebar di SQL
Diagram jaringan produksi	Sedang	infrastructure/TODO
HA backup RPO/RTO	Sedang	Tidak di repo
Prometheus/alerting	Rendah	Tidak ada di codebase
Modul kas/biaya/pajak implementasi	Tinggi	Desain 14 ada, coverage parsial
SSE/FCM contract lengkap	Sedang	Prompt ada, spec pendek
CI pipeline terpusat	Sedang	Disebut di 07, tidak terdokumentasi
Web ERP produk (non migrasi-ui)	Sedang	Belum dimulai
Trigger catalog `logika.*`	Tinggi	Untuk AI maintenance

Area berisiko — dokumentasi lemah¶

Area	Risiko operasional	Rekomendasi
Urutan DDL CH↔PG	Consumer crash produksi	Simulasi di runbook + checklist PR
Global Kafka reset di DEV	Salah ke prod	Dokumentasi OPERATING_MODEL + UI guard sudah ada — perlu audit berkala
`search_path` / pool tenant	Kebocoran data	Troubleshooting doc dibuat; perlu contoh log
Cutover big-bang	Downtime & rollback	Perlu runbook cutover terpisah (belum ada)
Posting jurnal via API (stub)	Klien mengira API lengkap	Tandai di OpenAPI / api/TODO
unmapped legacy fields	Data hilang saat ETL	Laporan ada — perlu gate sebelum tenant baru
MV ClickHouse rebuild	Dashboard kosong sementara	Sudah di clickhouse-patterns — perlu SOP operasi

Prioritas dokumentasi berikutnya¶

Runbook cutover big-bang — langkah, rollback, rekonsiliasi gate
OpenAPI generated + matriks endpoint — sinkron dengan backend/src
Katalog trigger & fungsi logika — untuk maintenance AI/human
Runbook tenant baru end-to-end (PG + ETL + CH + CDC + API)
Diagram infrastruktur produksi — port, firewall, Tailscale
Dokumentasi modul draft/approval (database/fitur/) di docs/postgresql/
MkDocs/Docusaurus config — mkdocs.yml atau sidebars.js (belum dibuat)

Saruhan untuk AI-assisted maintenance¶

Mulai dari README.md + AGENTS.md
Gunakan references/source-of-truth-index.md sebelum mengarang
Untuk perubahan schema: selalu sebut file migrasi V### dan urutan CH/PG
Tandai [BELUM DIVERIFIKASI] di dokumen baru jika tidak ada di kode

Statistik (perkiraan)¶

Metrik	Nilai
File markdown baru di `docs/`	~35
Dokumen fondasi wajib	10/10 ✅
Dokumen seri 00–15 dipindah	0 (sengaja)
Runbook dipindah	0 (indeks saja)

Maintainer: perbarui file ini setelah batch dokumentasi berikutnya.