Skip to content
Elimi Docs

Architecture handover

Architecture handover

Section titled “Architecture handover”

Audience: backend, product, leadership
Status: specced
Owns: backend
Depends on: System architecture, Backend stack ADR, Contracts hub

Index of the backend architecture design package. Narrative pages on this site stay the human product SoT. CAP HTTP is implemented in elimi-ecosystem/apps/cap (openapi/openapi.yaml + Express); the workspace-root cap-openapi.yaml is kept in lockstep for this docs site. Historical CAP design through §29 is archived under reference-docs/v2/.

Design source of truth (ecosystem root)

Section titled “Design source of truth (ecosystem root)”
Artifact Contents
HANDOVER.md Manifest and reading order (see also reference-docs/v2/HANDOVER.md)
backend-architecture-discussion.md Living design doc (sections §1–29; §17 folded into §16) — CAP SoT through §29 in reference-docs/v2/
orchestrator-openapi.yaml Orchestrator REST — validated OpenAPI 3.1 (35 operations). Live HTTP SoT is elimi-ecosystem/apps/orchestrator/openapi/openapi.yaml; this root file is the docs seed
cap-openapi.yaml CAP REST — OpenAPI 3.1 (211 operations). Live HTTP SoT is elimi-ecosystem/apps/cap/openapi/openapi.yaml; this root file is the docs seed (copy after CAP OpenAPI edits, then pnpm sync:openapi)
lms-openapi.yaml LMS REST — OpenAPI 3.1 (onboarding, catalogue, authoring, entitlements, player, assessments, certificates, staff)
orchestrator-schema.prisma Orchestrator Prisma design seed. Implemented schema + migrations live in elimi-ecosystem/apps/orchestrator/prisma/
cap-schema.prisma CAP Prisma design seed (also archived in reference-docs/v2/). Implemented schema + migrations live in elimi-ecosystem/apps/cap/prisma/
lms-schema.prisma LMS Prisma — lms_users, onboarding, catalogue, entitlements, progress, SCORM sessions, LMS certificates; not yet migrated
pkg/ (@yourorg/common) Shared kit — errors, envelope, pagination, ULID, OTel, outbox, RBAC helpers, Money/PhoneNumber
proto/ (@yourorg/proto) gRPC — IdentityService.VerifyIdentity, IdentityService.ProvisionAccount, PaymentService.InitiatePayment, lms.v1.RecommendationsService.RecommendCourses

Section map (living design doc)

Section titled “Section map (living design doc)”
  • §1–9 — documents needed, architecture, tables, JSON usage, deployment, phased plan, gaps
  • §10, §13 — workflow abstraction (config-driven stages + closed strategy set), including form_submission
  • §11 — SLA/SLO (API latency vs workflow SLAs)
  • §12 — Postgres decision
  • §14 — audit vs analytics split
  • §15 — payment (CAP prices; Orchestrator processes)
  • §16 — full REST contract review (basis for both OpenAPI specs); NIN / storage assetId folded here (§17 gap in numbering)
  • §18 — NOS document model
  • §19 — response envelope, cursor pagination, ULID
  • §20 — Event catalog
  • §21 — gRPC contracts → @yourorg/proto
  • §22 — RBAC matrix
  • §23 — Prisma conventions (enum vs String+CHECK)
  • §24 — OOP patterns → Coding standards
  • §25 — UNIT_ASSESSOR / AssessorAssignment; RPL has no unit sign-off
  • §26 — implementation checklist (pkg → proto → Orchestrator → CAP → hardening)
  • §27 — Job Posting / Retained Assessor Request rename + sector-experience marketplace gating
  • §28 — RPL single-application page (receipt, Evidence Vault, interview forms, signatures, stages, calendar)
  • §29 — Candidate dashboard composed endpoints

How docs sync works

Section titled “How docs sync works”

From elimi-documentation/:

Terminal window
pnpm sync:all
Script Copies
sync:openapi ../orchestrator-openapi.yaml → openapi/orchestrator.yaml; ../cap-openapi.yaml → openapi/cap.yaml; ../lms-openapi.yaml → openapi/lms.yaml; then → public/openapi/
sync:contracts proto orchestrator/v1 + lms/v1 → contracts/proto/; events → public/contracts/

Browse published contracts: Contracts hub · Orchestrator REST · CAP REST · LMS REST · Events · gRPC.

Not yet done (do not over-read the artifacts)

Section titled “Not yet done (do not over-read the artifacts)”
  • CAP domain HTTP for RPL/NSQ/centres is implemented in elimi-ecosystem/apps/cap (OpenAPI 182 operations, Prisma migrated in-app). Root cap-openapi.yaml / cap-schema.prisma are design seeds — copy OpenAPI from the app after contract changes
  • Orchestrator REST is implemented in elimi-ecosystem/apps/orchestrator (OpenAPI 35 operations). Copy app YAML to orchestrator-openapi.yaml after contract changes, then pnpm sync:openapi here
  • Security Audit service scoped but not phased for build
  • Open product questions: Awarding Body / Platform Staff tiering; whether InterviewEvaluation gets default/typed signature treatment; Job Posting Marketplace broader public discovery (default remains eligibility-gated by approved status + sector experience)

Suggested reading order: living design doc (§27–29 for CAP deltas) → CAP OpenAPI + Prisma → install pkg / proto → implement services per §26 / CAP checklist.

Monorepo ops (implemented): VPS activate, seeds, and deploy-time console commands are documented on this site under CI/CD and Console commands; runbook detail lives in elimi-ecosystem/infra/deploy/README.md.