Engineering handbook · Source-backed views
Understand the system.
Follow the decisions.
From a browser request to durable learning evidence: the components, conversations and Go contracts that make ZubLMS work.
These are views of the local source, reviewed on 3 November 2026. Optional adapters are labelled; a diagram is not evidence of deployment or certification. Go remains a modular monolith. PostgreSQL stores both application data and River jobs.
Explore the architecture
System components and trust boundaries
Browser, Go processes, persistent services and optional integrations.
How to read this diagram & source references
- This is a component view, not a claim that every optional integration is enabled.
- The Go API owns authorisation; PostgreSQL RLS is another boundary. River stores jobs in PostgreSQL, not Redis.
- Local development uses Vite and host processes; release packaging uses built web assets.
Source references in the repository:
cmd/api/main.gocmd/worker/main.godeploy/release/compose.ymldocs/ai-assistance.md
The downloadable Mermaid file provides a text representation of every node and connection.
The boundaries that matter
Authority stays on the server
Session-derived membership, permissions and tenant-bound transactions protect data. Hidden buttons and client-side filters are not access controls.
Published learning stays stable
Drafts are revisioned. Enrolments pin published versions, progress commands are deduplicated, and completion evidence is separate from a rendered certificate.
External output stays untrusted
Packages run on an isolated origin. AI output requires validation and human review. Provider availability does not imply a fully automated workflow.
Recovery is an explicit responsibility
Key material, database state, the recovery journal and object bytes must be recoverable together. Automatic unsealing and off-server backups remain deferred.
All diagrams, ready to share
SVG stays sharp when enlarged. Mermaid source can be reviewed and edited. These links also work without JavaScript.
Browser, Go processes, persistent services and optional integrations.
View SVGDownload sourcePublic transport and composition connect domain services to shared infrastructure.
View SVGDownload sourceBrowser redirects to Keycloak; the API establishes the authorised workspace session.
View SVGDownload sourceAuthors publish immutable content; managers assign a specific published version.
View SVGDownload sourceAccepted progress and server-scored assessments lead to durable completion and queued rendering.
View SVGDownload sourceA report is queued, generated under scope checks and downloaded through an authorised endpoint.
View SVGDownload sourceSelected resources are authorised before and after a bounded provider request.
View SVGDownload sourceReviewed immutable package versions run in an isolated origin and persist acknowledged runtime state.
View SVGDownload sourceAn explicit authorised send records recipients and lets workers deliver configured channels.
View SVGDownload sourceExplicit lifecycle commands keep migrations separate from normal application startup.
View SVGDownload sourceSelected real Go structs and interfaces; parameters are abbreviated for readability.
View SVGDownload sourceConsumer-facing object interfaces and concrete storage adapters.
View SVGDownload sourceThe assistance service consumes bounded provider interfaces and tenant-scoped persistence.
View SVGDownload sourcePublication pins course versions; learner launch checks ownership and stage prerequisites before creating or reusing a course cycle.
View SVGDownload source