nx-design

The drawings and the contracts for the platform we run: one service today (simple-lms), the plugins it consumes, and the bundles that describe them. Every folder is an OKF bundle: markdown with YAML frontmatter is the source, and an .html sits beside each concept for humans, with the mermaid diagrams rendered.

Services

nx-master — the agent-first CRM: chat authorization, roles as data, the MCP surface, and one bot per user.
simple-lms — the school service: what it is, architecture and seams, RBAC, money flows, the full data model, every screen with its gate, deployment, testing and i18n.

Plugins

The settings contract — how a plugin declares settings the host can render without knowing it.
nx-register — money, voids, period locks and drawer counts.
Access — users, roles, permissions: the interface the host checks against.
ADR-001: nx-audit — the audit log as the next plugin: contract, au_ schema, history migration, retention and export.

How this bundle is built

Markdown is the source of truth; frontmatter carries type, title, description, tags, provenance and verification.
npm run render writes the .html beside each concept; npm run check validates frontmatter, links and every mermaid fence; make serve renders and serves the whole bundle at http://localhost:8787/.
Diagrams are ```mermaid fences inside the markdown, so agents read the same graph humans see.

Diagram colours

Colour carries meaning, so it must not be chosen per diagram. These classes are declared at the end of a mermaid block and name the same things everywhere:

class	colour	means
`host`	blue `#15314a`	code and data owned by the service (handlers, services, repos, host-side boot)
`plugin`	green `#163a2f`	code and settings owned by a plugin (`nx-register`, `nx-common`'s contract values)
`store`	amber `#3a2f16`	persistence: SQLite itself, `re_*` tables, an invariant written in the schema
`contract`	purple `#2a1f3a`	a shared interface or contract that neither host nor plugin owns
`ext`	purple-grey `#2a1f3a`	outside the system: the browser, a CDN, another service
`bad`	red `#4a1f28`	a refusal or failure path (403, fail-closed branch, rejected write)

flowchart LR h["host"]:::host --> p["plugin"]:::plugin p --> s[("store")]:::store h -.-> c["contract"]:::contract c -.-> e["external"]:::ext h --> b["refused"]:::bad classDef host fill:#15314a,stroke:#2f5d84,color:#e6edf7 classDef plugin fill:#163a2f,stroke:#2f7d5b,color:#e6edf7 classDef store fill:#3a2f16,stroke:#8a7327,color:#f2e8cf classDef contract fill:#2a1f3a,stroke:#6b4f8a,color:#e9dcf5 classDef ext fill:#2a1f3a,stroke:#6b4f8a,color:#e9dcf5 classDef bad fill:#4a1f28,stroke:#8a3f4f,color:#f7c9d2

Nodes left uncoloured take the renderer's base theme (dark blue), which is the right default: a diagram only earns colour when the colour says something.

Rendered from index.md · OKF bundle · regenerate with npm run render