Skip to main content

Technical Decisions — Overview

This is the entry point for the technical decision suite. Each section here is a one-paragraph summary. Full decisions, options, and rationale live in the respective TD file.

What This Suite Covers​

Six documents that translate the platform's architecture and policies into concrete technical decisions. They are sequenced by dependency — each file builds on decisions confirmed in the ones before it. Where a decision is not yet confirmed, the file documents the options and what is needed to resolve it.

Decision Status used across all files: ✅ Decided — confirmed, can be built against · 🔍 Under Analysis — options identified, do not build against yet · 📅 Pending Session — requires a session or external input

TD1 — Core Tech Stack​

File: TD1_CoreTechStack.md

  • Two runtimes by purpose: FastAPI (Python) for computation-heavy engines, Node.js for I/O-heavy and high-concurrency engines
  • FastAPI engines: Eligibility, Rule Engine, Allocation, ITS Sync, Capacity Balance, HR Bank
  • Node.js engines: RBAC, Identity Bridge, Config Cascade, Notifications, Audit Log, Miqaat Lifecycle, and others
  • API Gateway in front of all services — concept confirmed, technology under analysis
  • Seven shared concerns across both runtimes: gateway routing, event schema, error response format, structured logging, health endpoints, auth passthrough, config access

TD2 — Event-Driven Structure​

File: TD2_EventDrivenStructure.md

  • Two communication patterns: Pattern A (synchronous HTTP call to Core before proceeding) and Pattern B (asynchronous event publish after a state change)
  • Standard event envelope confirmed: eventId, eventType, schemaVersion, timestamp, idempotencyKey, sourceModule, miqaatId, itsId, correlationId, payload
  • Module identity via API key; user identity via ITS token — two separate layers
  • Event publish authorization: three checks confirmed (sourceModule match, eventType in registered list, schema valid)
  • Enforcement mechanism (Core gateway vs direct bus ACLs) — 🔍 under analysis pending messaging technology decision

TD3 — Contracts​

File: TD3_Contracts.md

  • Three contract families: ITS Integration (C-001, C-005), Core API contracts (C-010 to C-019, one per engine), Event contracts (C-020+)
  • C-001: ITS SSO token validation at the Identity Bridge only — Core does not take over module login flows
  • C-005: Core is the single ITS data ingestion point, replacing 32 individual module syncs — mechanism under analysis
  • C-010 to C-019: one contract per Core engine covering endpoint, auth type, request/response, SLA, versioning
  • All Core APIs return a standard success/error envelope with requestId

TD4 — Module Build Guidance​

File: TD4_ModuleBuildGuidance.md

  • Modules stop owning: authentication, permission tables, eligibility logic, ITS sync, business rules in SQL, notification delivery, cross-module calls
  • Modules retain full ownership of: data, business logic, UI, deployment, and their own event schemas
  • System Definition Document required before any module build begins — no exceptions
  • Four migration tiers: Greenfield (Core-compliant from day one), Tier B (modern REST — progressive integration), Tier C (legacy .NET — HTTP calls + outbox pattern), Tier D (stored-proc — outbox inside same DB transaction, Core relay agent publishes)

TD5 — Infrastructure​

File: TD5_Infrastructure.md

  • Confirmed requirements: Docker for all Core services, three isolated environments, independent CI/CD per module, audit log durability, event bus replay, consumer groups, DLQ, topic-level access control, horizontal scaling, auto-scaling preference, structured JSON logging, distributed tracing via correlationId
  • Under analysis: container orchestration, API gateway technology, database per engine, messaging technology, observability tooling
  • All technology decisions blocked on cloud provider and network topology — resolved in the ITS infrastructure session
  • Eight specific questions documented as the input brief for that session

TD6 — Security​

File: TD6_Security.md

  • Core security posture confirmed through architecture: defense in depth, least privilege, zero trust, breach containment by API key revocation, immutable audit trail
  • Platform-specific threats mitigated by design: allocation fraud (Core is sole allocator), event impersonation (sourceModule check), privilege escalation (write endpoints blocked at gateway)
  • Confirmed module requirements: no local permission tables, no ITS data copies, no direct inter-module calls, no secrets in source control, HTTPS only
  • Pending dedicated security session: network security model, encryption at rest, PII handling policy, compliance requirements, log retention, penetration testing schedule

Pending Sessions​

Three sessions are required before blocked decisions can be resolved:

SessionUnblocks
ITS technical sessionC-001 (token format and lifecycle), C-005 (sync mechanism — pull / push / hybrid)
ITS infrastructure sessionCloud provider, VPC topology, orchestration, DB services, CI/CD toolchain (TD5)
Dedicated security sessionNetwork security, encryption at rest, PII policy, compliance, pen testing (TD6)

Foundation Files (pre-TD)​

These files were completed before the TD suite and are the source of the policies and principles the TD files build on:

FileContent
ITS_Core_Architecture_Brief.mdCore engine list, federation model, platform overview
CoreRolesRespons.mdCore responsibilities, miqaat lifecycle, data flow
CoreUtilities.mdOperational utilities, AI utilities, exclusion table
core_design_system.mdDesign token system, component library, accessibility
BusinessModulesAndPolicies.mdPlatform policies, system definition process, RBAC federation