# 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:
```yaml
---
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.