Architecture — Index

Miqaat Core Platform

This folder contains the detailed architecture design for the Miqaat Core Platform. These documents sit one level below the Technical Decisions (TD files) — where the TD files confirmed what to build and why, the Architecture files define exactly how each part is designed.

Read the TD files first. Every decision here traces back to a confirmed decision in TD1–TD6.

---

How to Read This Folder

The documents are sequenced by dependency. Service Decomposition first — everything else references the services it defines. Auth before Security — Security builds on the Auth model. Event Catalog before Event Schemas — the catalog defines what exists, the schemas define the exact structure.

---

Documents in This Folder

01 — Service Decomposition

File: 01_ServiceDecomposition.md · Status: ✅ Draft

Breaks the 15 confirmed Core engines into individual microservices. For each service: runtime, exact responsibilities, data store, what it reads from, internal dependencies, key endpoints, and open assumptions.

Covers:

• All 15 services with boundaries, runtime, and scale characteristics defined
• FastAPI vs Node.js assignment rationale per service
• Inter-service dependency map with "Reads From" column
• API Gateway routing table (all path prefixes → service)
• Domain Event Schema Registry and ITS Sync Engine documented separately
• 37 open assumptions consolidated in Section 8

---

02 — API Design Standards

File: 02_APIDesignStandards.md · Status: ✅ Draft

Conventions that apply to every Core API endpoint across all 15 services. Module teams read this once before reading individual contracts.

Covers:

• Base URL structure and versioning rules (MAJOR vs MINOR)
• Required request headers and Gateway-set headers
• X-Correlation-Id tracing chain — from X-Request-Id through to requestId in the response
• Standard success/error response envelope
• Pagination (cursor-based), rate limiting, idempotency
• Read/write split enforcement and health endpoint standard

---

03 — API Contracts

File: 03_APIContracts.md · Status: ✅ Draft

Full endpoint-level specs for C-010 to C-019 (module-facing contracts), plus Audit Log, Notification Dispatch, and ITS Sync Engine internal endpoints.

Covers:

• C-010 RBAC Engine — including the Scale Problem, Team Adaptation Challenge, Scanning/Kiosk special case, GET /v1/rbac/permissions bulk fetch, wildcard permission format, and what Core will provide to help module teams
• C-011 to C-019 — Eligibility, Config Cascade, Miqaat Lifecycle, Allocation, Zone Mapping, Vendor Registry, HR Bank, Capacity Balance, Task Engine
• Audit Log (Platform Admin only) and Notification Dispatch
• Pending contracts table (C-001, C-005 — blocked on ITS Technical session)

---

04 — Event Catalog

File: 04_EventCatalog.md · Status: ✅ Draft

Complete inventory of all event types on the platform — Core-published and module-published.

Covers:

• Event naming convention (domain.action, lowercase, past tense)
• 9 Core-published events (C-020 to C-026) with producer, subscribers, fire conditions, retention, and replay requirements
• 40+ module-published events across 10 domain groups
• Full Producer → Consumer cross-reference map
• Retention tiers, replay requirements, event bus operational requirements
• Subscription management process

---

05 — Event Schemas

File: 05_EventSchemas.md · Status: ✅ Draft

Formal payload schemas for every event type in the catalog.

Covers:

• Standard envelope schema with field-level definitions
• Schema versioning (MAJOR/MINOR) and parallel version support window
• All 9 Core-published event payload schemas (C-020 to C-026)
• 8 module-published event schemas for events Core subscribes to — with minimum required fields
• Schema registry registration process

---

06 — Authentication Flow

File: 06_AuthFlow.md · Status: 🔧 Partial — ITS token specifics pending C-001

End-to-end authentication design for all call types into Core.

Covers:

• Two-identity model — ITS bearer token (human) vs API key (system)
• Identity Bridge — what it validates, strips, and sets; what it rejects before routing
• Sequence diagrams for user-initiated and system-initiated flows
• X-Correlation-Id full lifecycle — module → Bridge → engine → internal calls → response echo
• API key management — issuance, rotation (24-hour overlap), revocation
• Platform Admin authentication — ITS SSO + PLATFORM_ADMIN RBAC role; bootstrapping problem and seed process
• Internal engine-to-engine calls — bypass the Bridge, credentials TBC
• ⏳ ITS token validation details (claim names, JWKS URL, refresh mechanism) — pending C-001

---

07 — Authorization Model

File: 07_AuthorizationModel.md · Status: ✅ Draft

Core RBAC design — the permission authority for all 32 modules.

Covers:

• Permission string format (resource:action) and wildcard behaviour (volunteer:*) — confirmed
• Role levels — platform (PLATFORM_ADMIN only) vs miqaat (all other roles)
• Role hierarchy — proposed model with open questions flagged for RBAC technical session
• Role assignment rules — confirmed items and open questions flagged for RBAC technical session
• /v1/rbac/check step-by-step evaluation logic
• Multi-scope — holding roles across multiple Miqaats simultaneously
• Temporal scoping — validFrom/validUntil on assignments and cache TTL implications
• The Gathri exception — current position and boundary questions for business session

---

08 — Security Architecture

File: 08_SecurityArchitecture.md · Status: 🔧 Partial — infrastructure and tooling pending sessions

Security design implementing the TD6 posture in practice.

Covers:

• 8 confirmed security principles from TD6 (single entry, zero trust, credential stripping, read/write split, immutable audit, secrets out of config, TLS everywhere, least privilege)
• Network topology — confirmed structure; cloud provider and VPC layout pending Infrastructure session
• API Gateway security controls — all confirmed from TD2/TD3
• Audit log design — structure, what gets audited, immutability model, correlationId linkage
• Module security requirements — 6 confirmed pre-go-live checklist items
• ⏳ TLS tooling, secrets management tooling, encryption at rest, incident response — pending sessions

---

Status Overview

#	Document	Status	Prerequisite
01	Service Decomposition	✅ Draft	TD1, TD2
02	API Design Standards	✅ Draft	TD3, Service Decomposition
03	API Contracts	✅ Draft	API Design Standards
04	Event Catalog	✅ Draft	TD2, Service Decomposition
05	Event Schemas	✅ Draft	Event Catalog
06	Auth Flow	🔧 Partial	TD2, TD3, C-001 session outcome
07	Authorization Model	✅ Draft	Auth Flow
08	Security Architecture	🔧 Partial	TD6, Infrastructure session outcome

---

Pending Sessions Required to Complete This Folder

These sessions are not yet scheduled. Documents marked 🔧 Partial are blocked on one or more of these.

Session	Blocks
ITS Technical session (C-001)	06 Auth Flow — token claim names, JWKS URL, refresh mechanism, token revocation
RBAC Technical session	07 Authorization Model — role hierarchy direction, assignment rules, delegation model
Dedicated Infrastructure session	06, 08 — network topology, engine-to-engine credentials, secrets tooling, TLS configuration
Dedicated Security session	08 — audit log retention, encryption at rest, incident response, module security checklist completion
Scanning/Kiosk offline session	03 — offline RBAC approach and device release management
Gathri business session	07 — Gathri exception boundary between Core RBAC and module responsibility

---

What the TD Files Already Decided

These are confirmed. Architecture documents implement these decisions — not revisit them.

Decision	Source
FastAPI for computation-heavy engines, Node.js for I/O engines	TD1
API Gateway in front of all services	TD1
Standard event envelope fields	TD2
Two communication patterns (sync HTTP + async event)	TD2
Standard request/response envelope for all Core APIs	TD3
Three event publish authorization checks	TD2, TD3
ITS is the only identity provider	TD3 C-001
Core does not take over module login	TD3 C-001
Read/write endpoint split — module keys read-only	TD2
At-least-once delivery, consumers must be idempotent	TD2