Organization module
Organization module
Section titled “Organization module”Audience: backend, product
Status: specced
Owns: backend
Depends on: Payment architecture, System architecture, Event catalog, RBAC matrix, Orchestrator data model
Implementation checklist: elimi-ecosystem/ORGANIZATION_IMPLEMENTATION_PLAN.md (ORG-* tasks).
Paying organizations buy prepaid cohorts (slot invoices) for LMS and/or CAP. Workmasters is a future products[] value only. Learners and candidates keep using product apps; organization staff use org-scoped APIs.
Service ownership
Section titled “Service ownership”| Concern | Owner |
|---|---|
| User login (email, Google, OTP, password, delete) | Orchestrator Auth (existing) |
| Tenant profile, staff membership, cohort invoice, quote TTL, settlement policy, ecosystem operators, transaction list | Orchestrator |
| Application lifecycle, centre prices, CAP bulk enrol, pay-stage unlock | CAP |
| Level offerings, LMS bulk enrol, checkout unlock | LMS |
| Paystack webhook | Orchestrator (unchanged) |
Orchestrator does not store learner progress or application dossiers. CAP/LMS store organizationId and cohortId as opaque ULIDs (no cross-DB FK).
flowchart TB Client[Org client] OL[Orchestrator] CAP[CAP] LMS[LMS] PS[Paystack] RMQ[RabbitMQ] Client --> OL Client --> CAP Client --> LMS OL -->|quote prices gRPC| CAP OL -->|quote prices gRPC| LMS OL --> PS PS -->|webhook| OL OL -->|cohort.activated| RMQ RMQ --> CAP RMQ --> LMS CAP -->|ProvisionAccount| OL LMS -->|ProvisionAccount| OLIdentity
Section titled “Identity”Intent and membership
Section titled “Intent and membership”- Registration uses existing
/v1/auth/*withintentsincluding"organization". - Do not put
userIdonOrganization. OrganizationStaff:(organizationId, userId)unique; v1role = SUPER_ADMIN(invite-only additional staff). StatusINVITED|ACTIVE|SUSPENDED.- One user may belong to many organizations. Routes take
:organizationId. Access JWT stays{ sub, email, intents }— no org id in the token (v1). - Org staff are not provisioned as
CapUser/LmsUserunless later enrolled as learner/candidate. - After verify (or first Google),
POST /v1/organizationscreates the tenant and the caller as super admin in one transaction, thenorganization.created.
Last super admin
Section titled “Last super admin”POST /v1/auth/delete-account returns 409 organization.last_super_admin if the user is the last ACTIVE SUPER_ADMIN of any ACTIVE organization. Archive the org first, or add another super admin. User delete never cascade-deletes cohorts, payments, learners, or applications.
Ecosystem operators
Section titled “Ecosystem operators”People who run Elimi (not a customer org) live on Orchestrator:
EcosystemStaff+ rolesSUPER_ADMIN|FINANCE|SUPPORT- Intent
"platform"for fan-out; not a substitute for the membership row - Seed
SEED_PLATFORM_ADMIN_*into this table cap_admin/lms_adminremain product grants (centres, catalogue, LMS authoring)
Cross-product money rules are not edited from CAP /admin/platform-config.
Cohort (commercial aggregate)
Section titled “Cohort (commercial aggregate)”Created on OL. Status PENDING_PAYMENT | ACTIVE | COMPLETED | CANCELLED | EXPIRED.
Line items snapshot unit price at quote time:
- LMS:
levelOfferingId,slots - CAP:
centreId,applicationType(RPL|NSQ),slots
products[] is a string array (lms, cap, later workmasters). List filter productType=cap,lms uses overlap (multiple values).
Completed (v1): every line item consumedSlots >= slots. Unused-but-paid capacity does not block completion once consumed; rejected/withdrawn people still consumed a seat until release.
Quote TTL
Section titled “Quote TTL”- Persist quote as
PENDING_PAYMENTwithexpiresAt = createdAt + 24h(ORGANIZATION_COHORT_QUOTE_TTL_HOURS). - Do not create a Paystack session until
POST .../cohorts/:id/pay. - Job marks
EXPIRED;cohort.expired. - Webhook SUCCESS after
EXPIREDmust not activate. Finance reconciles manually.
OL recomputes price via CAP/LMS gRPC. Client-sent totals are ignored.
Payment
Section titled “Payment”OL is the business service for this SKU: client-facing pay HTTP lives here; processing still uses the existing Payment adapter and payments row.
referenceType: organization_cohortreferenceId: cohortIduserId: paying staff user- On success: cohort
ACTIVE, snapshot settlement policy (effectiveFrom <= paidAt), outboxcohort.activated
LMS revenue on the invoice is always platform. CAP centre line items follow settlement policy (below). One wallet movement at this event — not again at candidate pay.
Settlement policy
Section titled “Settlement policy”OL PlatformPolicy key organization_cohort_settlement, versioned, effectiveFrom. New version only (no in-place edit). Authors: EcosystemStaff FINANCE or SUPER_ADMIN.
Default v1:
{ "mode": "split", "platformSharePercentage": 20, "centreSharePercentage": 80}mode |
CAP centre line items |
|---|---|
split |
shares must sum to 100 |
platform |
no centre credit |
centre |
100% to those centres |
Do not stack CAP processing_fee_percentage on this invoice. Persist settlementSnapshot on the cohort. No automatic refund of unused slots in v1.
CAP WalletTransaction idempotency for this path is (paymentId, centreId) because one invoice can credit many centres.
Seats and sponsored pay
Section titled “Seats and sponsored pay”CohortSeat: CONSUMED | RELEASED. Unique active consume per (lineItemId, userId).
Bulk enrol (org) consumes a seat and creates:
- CAP: DRAFT application with
organizationId,cohortId, centre, type, trade — then the normal CAP flow (submit, centre form approval, payment stage). - LMS: level enrollment / entitlements with
ORGANIZATION_SEAT+cohortId.
At POST /applications/:id/pay and LMS checkout:
- Active
CohortSeatfor this person - Cohort
ACTIVE - SKU matches (centre+type or offering)
→ 200 { settlement: "organization_cohort", checkoutUrl: null, organizationId, cohortId } and synchronous unlock (same as payment.completed for self-pay). No provider checkout, no second Payment, no second wallet credit.
GET .../payment-quote exposes the same settlement discriminant.
Do not infer sponsorship from email. Do not attach an open self-pay application to a cohort. Bulk enrol 409 if an open self-pay row exists for that person + SKU.
Delete / withdraw
Section titled “Delete / withdraw”| Actor | Sponsored application / level enrollment |
|---|---|
| Learner / candidate | No hard delete. No withdraw (409 sponsored.not_withdrawable) |
| Org super admin | Release until CERTIFIED / offering completed: mark withdrawn, RELEASED, return slot, cohort.seat_released |
| After certified/completed | No release |
Catalogues
Section titled “Catalogues”- CAP: approved centres + latest RPL/NSQ prices + logo (
logoAssetIdresolved likeGET /centres). New endpoint — existing centre list has no prices. - LMS: published level offerings with price, level, trade.
Overview metrics
Section titled “Overview metrics”Timezone: Africa/Lagos. Query year= (default current year) on cards and chart.
| Card | Source | Definition |
|---|---|---|
| Total / pending / ongoing / completed cohorts | OL | pending = PENDING_PAYMENT; ongoing = ACTIVE; completed = COMPLETED; total excludes CANCELLED |
| Total staff | OL | ACTIVE organization staff (not year-scoped) |
| Total applications | CAP | submittedAt not null, that year |
| Total certified | CAP | certificate issuedAt in year |
| Total learners | LMS | distinct learners with org enrollment created that year |
Chart (flows, 12 months): enrolled = created that month; inProgress = entered in-training / payment-settled in-assessment that month; completed = certified / offering complete that month. OL BFF merges CAP + LMS series.
Table status wire: pending | in_progress | completed | withdrawn (see implementation plan).
OL BFF: GET /v1/organizations/:id/overview and .../progress. Learner and application tables are product APIs. v1: if a product aggregate RPC fails, the BFF fails the request (no silent zeros).
Notifications
Section titled “Notifications”Reuse GET/PUT /v1/notifications/preferences (email, in_app; sms default off). Per user, not per org.
Operational templates (respect prefs): cohort payment succeeded/failed, cohort activated, slots low (≤10% or ≤5 remaining, once), bulk enrol completed, staff invited, receipt ready. Invite/provision passwords stay existing in-process OL mail.
CSV templates
Section titled “CSV templates”GET text/csv with header name,email and example rows that the parser rejects (reserved name prefix EXAMPLE DO NOT IMPORT, invalid email, @elimi.invalid). Do not use examples that would consume real slots.
Bulk payload: per SKU either JSON person array or csv, not both.
Extraction seam
Section titled “Extraction seam”If Organization becomes its own service later, move together: Organization, OrganizationStaff, EcosystemStaff, PlatformPolicy (settlement), Cohort*, org REST, ResolveOrganizationMembership. CAP/LMS keep opaque ids and events. Payment processing can remain on OL.
See also
Section titled “See also”- Checklist →
elimi-ecosystem/ORGANIZATION_IMPLEMENTATION_PLAN.md - Payment architecture · Event catalog · RBAC