Business Processes
The dynamic views show how the containers cooperate on a specific business operation. They're sequence-style - each arrow is auto-numbered in execution order - and they're rendered from the same Structurizr model as L1 and L2, so changes to the model flow through automatically.
Source of truth
Defined in /root/olly/docs/architecture/workspace.dsl (Structurizr DSL). Open standalone: ↗ structurizr.dev.hiolly.com.
| Process | What it shows |
|---|---|
| Quote → Bind | Broker quotes a scheme, binds, policy issuance saga runs, welcome email goes out. |
| Member Enrolment | HR adds a member to a group scheme, eligibility pre-flight, enrolment, welcome email. |
| Member Onboarding (MEM-ONB) - 0 (HR adds employee, PRIMARY) | HR signs into the Employer Portal, adds an employee, group-scheme mints a party + PIN via the identity service (which creates the party in policy-admin), enrolment fires, notifications sends the activation PIN. |
| Member Onboarding (MEM-ONB) - A (PIN, internal fallback) | God-mode operator provisions a member + emails a 5-digit PIN → member enters PIN → JWT minted via ROPC. Retained as a fallback for edge cases. |
| Member Onboarding (MEM-ONB) - B1 (secondary email magic link) | Signed-in member adds a secondary email → 15-min single-use token → clicks link → attribute appended in Keycloak. |
| Member Onboarding (MEM-ONB) - B2 (link Google) | Signed-in member picks Google account → id_token verified against Google JWKS → google_* attributes written. |
| Claim Adjudication | Provider submits a claim → eligibility → adjudication workflow → payout + decision email. |
| Prior Auth | PA request → rules + workflow → admin review (if flagged) → decision → provider + member emails. |
| Triage → Care | Member describes symptoms → LLM triage → disposition → book recommended care → confirmation email. |
| Billing Cycle | Monthly cron → invoice issued → HR pays → card capture → payment received (or dunning). |
Quote to Bind
Member Enrolment
Member Onboarding (MEM-ONB) - 0 (HR adds employee, PRIMARY)
Primary onboarding path. HR signs into the Employer Portal (JWT org_locator) and posts an employee to POST /api/group-scheme/{scheme}/members. group-scheme should mint a party + 5-digit PIN via the identity service (POST /internal/parties/mint-with-pin; identity is DB-free, so it creates the party by calling policy-admin's POST /internal/parties - #1161), enrol the member, and let notifications dispatch the activation-PIN email that transitions the member into Flow A verify-pin (also served by identity).
Not fully wired today
Audit against shipped Go code + docker-compose.yml: the frontend/backend contract on that endpoint is broken (frontend sends {firstName,lastName,email}, backend expects {memberPartyLocator} - see dashboardStore.ts:322 vs schemes.go:107). Group-scheme does NOT call policy-admin, does NOT emit member.enrolled, and no activation-email pathway is wired end-to-end. The ⏳ hops in the diagram below mark aspirational relationships. Only the bulk-enrolment path ships end-to-end (enrollment outbox → notifications SMTP direct).
Member Onboarding (MEM-ONB) - A (PIN, internal fallback)
God-mode operator provisions a member in Keycloak and emails a 5-digit PIN (Flow A) - retained as the internal fallback path for edge cases where Flow 0 can't be used. Member enters the PIN in the mobile app at POST /identity/onboarding/verify-pin; the identity service resolves the user by party_locator, rotates the Keycloak password to a random secret, and mints access + refresh tokens via ROPC against the web-member client. See Discussion #1160 §10 for the sequence detail. verify-pin + mint-with-pin were extracted from policy-admin into the identity service in #1161; the surviving link endpoints (Flow B1/B2) still live in policy-admin and follow into identity when PR #1159 lands.
Member Onboarding (MEM-ONB) - B1 (secondary email magic link)
Signed-in member submits a candidate secondary email address (Flow B1). policy-admin verifies the Bearer against Keycloak JWKS, stores a 32-byte token in Valkey (15-min TTL) keyed to the caller's sub, and sends a branded email carrying olly://link-email?token=... plus a member.dev.hiolly.com/auth/link-email web fallback. Redeem is single-use (Valkey GETDEL), cross-user guarded (entry.UserID == JWT.sub), then appends secondary_emails on the Keycloak user and rotates tokens so the new attribute lands in the access token.
Member Onboarding (MEM-ONB) - B2 (link Google)
Signed-in member links a Google account (Flow B2). Client collects a Google id_token - web via the Google Identity Services SDK popup, native via @react-native-google-signin on top of Play Services - and posts it to policy-admin. policy-admin verifies the Bearer against Keycloak JWKS, fetches Google's JWKS (https://www.googleapis.com/oauth2/v3/certs, cached 1h with rotate-on-unknown-kid), verifies signature + iss + aud + exp/iat, writes google_sub, google_email, google_email_verified_at on the Keycloak user, and rotates tokens so the new claims are present in the next access token.