hiveops-guide/DESIGN.md

hiveops-guide — Design (approved 2026-06-30)

One knowledge base that (a) teaches customers how each module works and (b) is the source-of-truth for module behavior (for admins + Claude). Markdown-authored, served by the backend API, read in a tabbed slide-out.

Decisions (Johannes, 2026-06-30)

1. Content = markdown files in git, still served via backend API calls (not bundled in the frontend).
2. Start over — greenfield. No backward-compat with the old content_json guides or the /api/v1/guides/{pageKey} contract; the Fleet "Guide" buttons get re-wired to the new API.
3. Retire the Guide Admin CRUD app. The guide keeps internal docs (technical guides for admins/Claude, audience: internal).

Content model — markdown in the repo

content/<app>/<module>/*.md — folder per module, one file per tab. Frontmatter:

---
module: devices.sw-deploy
title: Software Deployment
tab: The Data          # the tab label in the slide-out
order: 20              # tab order
audience: customer     # or "internal" (hidden from customers)
---
<markdown body>

Cross-cutting technical guides: content/technical/*.md (e.g. fleet→Kafka→devices, service map).

Backend (Spring Boot service kept; model replaced)

• Scans content/**/*.md at startup (cached), parses frontmatter + body.
• API (JWT-gated):
  • GET /api/v1/guide/nav?audience= → apps → modules → tabs tree
  • GET /api/v1/guide/modules/{module}?audience= → module + its tabs (markdown bodies)
• Remove the DB content_json model + admin CRUD endpoints. audience gates customer vs internal.

Frontend

• New tabbed slide-out reader (markdown rendered with marked); nav + tabs from the API.
• Retire the Guide Admin CRUD app.

Consumers

• Re-wire the Fleet "Guide" buttons (and future in-app guide entry points) to the new API.

Phases

1. Backend — markdown content model + nav/modules API; retire DB/CRUD.
2. Frontend — tabbed slide-out reader.
3. Content — author devices.sw-deploy + fleet.tasks as the pattern (Overview / Data / How-to + an internal Technical tab), then fan out to all modules.
4. Technical guides (internal) — fleet→Kafka→devices, service map, etc.