Skip to content

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.

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| OL
  • Registration uses existing /v1/auth/* with intents including "organization".
  • Do not put userId on Organization.
  • OrganizationStaff: (organizationId, userId) unique; v1 role = SUPER_ADMIN (invite-only additional staff). Status INVITED | 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 / LmsUser unless later enrolled as learner/candidate.
  • After verify (or first Google), POST /v1/organizations creates the tenant and the caller as super admin in one transaction, then organization.created.

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.

People who run Elimi (not a customer org) live on Orchestrator:

  • EcosystemStaff + roles SUPER_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_admin remain product grants (centres, catalogue, LMS authoring)

Cross-product money rules are not edited from CAP /admin/platform-config.

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.

  • Persist quote as PENDING_PAYMENT with expiresAt = 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 EXPIRED must not activate. Finance reconciles manually.

OL recomputes price via CAP/LMS gRPC. Client-sent totals are ignored.

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_cohort
  • referenceId: cohortId
  • userId: paying staff user
  • On success: cohort ACTIVE, snapshot settlement policy (effectiveFrom <= paidAt), outbox cohort.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.

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.

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:

  1. Active CohortSeat for this person
  2. Cohort ACTIVE
  3. 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.

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
  • CAP: approved centres + latest RPL/NSQ prices + logo (logoAssetId resolved like GET /centres). New endpoint — existing centre list has no prices.
  • LMS: published level offerings with price, level, trade.

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).

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.

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.

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.