79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
# ANSCORE — L2 & L3 Architecture Diagrams (PlantUML)
|
|
|
|
12 PlantUML diagrams covering Layer 2 (ANSVIS Communication Layer (CL)) and Layer 3 (Qt/QML UI).
|
|
|
|
## Files
|
|
|
|
| # | File | Type | Purpose |
|
|
|---|---|---|---|
|
|
| 01 | `01-system-context.puml` | Component | L1 / L2 / L3 overview with the 3 transports |
|
|
| 02 | `02-l2-internals.puml` | Component | L2 adapter layer + legacy + infrastructure |
|
|
| 03 | `03-l2-ownership.puml` | Component | Human-owned vs AI-coder vs reused legacy modules |
|
|
| 04 | `04-l3-internals.puml` | Component | Qt/QML shell / network / state / screens |
|
|
| 05 | `05-seq-configure-deploy.puml` | Sequence | Operator adds camera → AI task → deploys |
|
|
| 06 | `06-seq-live-events.puml` | Sequence | SSE event tail + evidence image/clip |
|
|
| 07 | `07-seq-liveview.puml` | Sequence | Liveview with bbox overlay sync |
|
|
| 08 | `08-seq-async-scan.puml` | Sequence | Async ONVIF scan via job queue |
|
|
| 09 | `09-seq-large-upload.puml` | Sequence | Large model upload via presigned URL |
|
|
| 10 | `10-deployment-topology.puml` | Deployment | Workstations / server / edges + ports |
|
|
| 11 | `11-l3-engineer-ownership.puml` | Component | 6-engineer L3 task allocation |
|
|
| 12 | `12-dependency-chain.puml` | Component | What gates what, critical path |
|
|
|
|
---
|
|
|
|
## How to view these in StarUML
|
|
|
|
StarUML doesn't render `.puml` natively, but the official **PlantUML extension** does:
|
|
|
|
1. In StarUML: `Tools → Extension Manager → search "PlantUML" → Install`
|
|
2. Restart StarUML.
|
|
3. `File → Open` → pick any `.puml` file from this folder, **or** use `Tools → PlantUML → Preview Diagram`.
|
|
4. To get an editable StarUML diagram (`.mdj`), use the extension's "Generate Diagram from PlantUML" feature, then save as `.mdj`.
|
|
|
|
Caveat: the extension renders accurately but the auto-generated StarUML elements may need light layout cleanup. If you want fully native StarUML diagrams, use these `.puml` files as the specification and recreate in StarUML — they're small enough that this takes ~10 min each.
|
|
|
|
---
|
|
|
|
## Alternative viewers (no install needed)
|
|
|
|
| Tool | How |
|
|
|---|---|
|
|
| **PlantUML web server** | <https://www.plantuml.com/plantuml> → paste any `.puml` content → get PNG/SVG/PDF |
|
|
| **VS Code** | Install the "PlantUML" extension by jebbs → `Alt+D` to preview |
|
|
| **JetBrains (CLion / IntelliJ / Rider)** | Install the "PlantUML Integration" plugin → preview on the side panel |
|
|
| **PlantUML CLI** (batch export) | `brew install plantuml` then `plantuml -tpng docs/diagrams/*.puml -o ../out/` |
|
|
| **PlantUML CLI** (SVG for slides) | `plantuml -tsvg docs/diagrams/*.puml -o ../out/` |
|
|
|
|
The web server is the fastest path if you just want to grab images for a slide deck or PDF.
|
|
|
|
---
|
|
|
|
## Render all to PNG in one shot
|
|
|
|
```bash
|
|
# from the repo root
|
|
brew install plantuml # macOS; or: apt install plantuml
|
|
mkdir -p out/diagrams
|
|
plantuml -tpng -o "$(pwd)/out/diagrams" docs/diagrams/*.puml
|
|
```
|
|
|
|
Output: one PNG per diagram in `out/diagrams/`.
|
|
|
|
For high-DPI presentations use `-tsvg` instead of `-tpng`.
|
|
|
|
---
|
|
|
|
## Editing tips
|
|
|
|
- Diagrams use only stable PlantUML features — should render in any PlantUML version ≥ 1.2022.0.
|
|
- Colors used: `#LightYellow` (human/lead), `#LightBlue` (AI/E2), `#LightGreen` (E3), `#LightPink` (E4), `#LightCoral` (E5), `#Lavender` (E6), `#LightGray` (reused legacy). Change consistently if you want a different palette.
|
|
- Each file declares its own `@startuml NAME` so multiple files can render to predictable filenames.
|
|
- Notes (`note bottom of ...`) are intentional — leave them in; they explain non-obvious decisions.
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- `docs/L2-L3-architecture.md` — same diagrams in Mermaid + accompanying prose.
|
|
- `contracts/openapi.v1.json` — the REST contract these diagrams reference.
|