Build internal platform knowledge base in guide API (audience: internal) #3

New Issue

2026-07-01T08:39:22-04:00

hiveiq commented

2026-07-01 08:39:22 -04:00

Make the guide API a queryable source-of-truth so admins and Claude understand HiveIQ without re-reading code or guessing.

Phase A — cross-cutting infra (platform.*), inline:

platform.topology — VMs/IPs/SSH/ProxyJump, deploy paths, registries
platform.kafka — topics + event schemas + producer/consumer map
platform.nginx-routing — CORS authority, blue/green backends, path-prefix rules
platform.data-stores — Postgres DB per service, table ownership
platform.gotchas — Common Mistakes, queryable

Phase B — per-service internal guides (technical.), parallel fan-out:

one grounded guide per microservice (~18), each read against its own code + verify pass

All content committed as DRAFT to develop, no deploy. Refs redesign #1.

Make the guide API a queryable source-of-truth so admins and Claude understand HiveIQ without re-reading code or guessing. **Phase A — cross-cutting infra (platform.*), inline:** - [ ] platform.topology — VMs/IPs/SSH/ProxyJump, deploy paths, registries - [ ] platform.kafka — topics + event schemas + producer/consumer map - [ ] platform.nginx-routing — CORS authority, blue/green backends, path-prefix rules - [ ] platform.data-stores — Postgres DB per service, table ownership - [ ] platform.gotchas — Common Mistakes, queryable **Phase B — per-service internal guides (technical.<service>), parallel fan-out:** - [ ] one grounded guide per microservice (~18), each read against its own code + verify pass All content committed as DRAFT to develop, no deploy. Refs redesign #1.

hiveiq commented

2026-07-01 09:30:26 -04:00

Phase A + B done and deployed to bcos.dev.

Phase A — 5 platform infra guides (topology, nginx-routing, data-stores, kafka, gotchas) — commit b102bba
Phase B — 19 per-service technical.<svc> guides, code-grounded + adversarially verified (0 invented facts) — commit 6542c4f
platform.kafka reconciled to 15 code-verified topics — commit a41f7d5

Deployed to bcos.dev: backend loads 36 docs across 34 modules; smoke test with admin JWT returns 200 + all 19 technical modules in nav; internal content correctly admin-gated (unauth → 401).

Stale docs the KB exposed were corrected (monorepo CLAUDE.md: remote, analytics). All content is DRAFT pending review.

Phase A + B done and deployed to bcos.dev. - **Phase A** — 5 platform infra guides (topology, nginx-routing, data-stores, kafka, gotchas) — commit b102bba - **Phase B** — 19 per-service `technical.<svc>` guides, code-grounded + adversarially verified (0 invented facts) — commit 6542c4f - platform.kafka reconciled to 15 code-verified topics — commit a41f7d5 Deployed to bcos.dev: backend loads **36 docs across 34 modules**; smoke test with admin JWT returns 200 + all 19 technical modules in nav; internal content correctly admin-gated (unauth → 401). Stale docs the KB exposed were corrected (monorepo CLAUDE.md: remote, analytics). All content is DRAFT pending review.

hiveiq referenced this issue from a commit

2026-07-01 10:47:18 -04:00

content(guide): platform infra knowledge base — topology, nginx-routing, data-stores, kafka, gotchas (DRAFT, Refs #3)

hiveiq referenced this issue from a commit

2026-07-01 10:47:18 -04:00

content(guide): per-service internal knowledge base — 19 technical.<svc> guides (DRAFT, Refs #3)

hiveiq referenced this issue from a commit

2026-07-01 10:47:18 -04:00

content(guide): reconcile platform.kafka catalog — 15 code-verified topics (Refs #3)

hiveiq referenced this issue from a commit

2026-07-01 10:47:18 -04:00

content(guide): customer-facing module guides across 13 SPAs (DRAFT, Refs #3)