Skip to main content

Roadmap: Building the Citadel Platform

[!NOTE] This is a summary. For detailed sprint-by-sprint implementation plan, see ROADMAP.md in the repository root.

1. Vision & Guiding Principles​

Vision: To build a highly scalable, resilient platform of composable services. This core will serve as a stable foundation for SaaS, PaaS, and eventually IaaS products, enabling rapid innovation without overengineering.

Guiding Principles:

  • Book-Keeper Principle: "One responsibility, ship it, done, forever useful." Avoid premature service splitting.
  • Domain-Driven Design (DDD): Service boundaries defined by business domains (Bounded Contexts).
  • API First: All communication through well-defined, versioned APIs.
  • Progressive Complexity: Build for SaaS first, design for PaaS extensibility, defer IaaS complexity.
  • S2S-First Auth: Platform services use service-to-service auth; user authorization handled in BFFs.

2. Phased Rollout Strategy​

Phase 0: Foundation (P0 - Stabilization)​

Goal: Establish core infrastructure and shared services.

  • iam-service: Authorization policy engine (users, tenants, roles, ABAC attributes, tenant lifecycle)
  • api-gateway: Request routing, token validation, enrichment
  • shell-app: Micro-frontend shell, multi-account, multi-tenant

Phase 1: Core Platform Primitives (P1)​

Goal: Build fundamental, composable building blocks.

  • book-keeper: Double-entry ledger abstraction (Postgres/KurrentDB/TigerBeetle)
  • workflow-service: Engine-agnostic orchestration (Temporal)
  • user-directory-service: PII query router for multi-IdP support
  • client-directory-service: OAuth client management router for multi-IdP
  • permissions-service: ReBAC engine (SpiceDB) - build only if needed

Phase 2: Essential Platform Services (P2)​

Goal: Add observability, communication, and compliance.

  • notification-service: Multi-channel notifications (email, SMS, webhooks)
  • audit-service: Compliance audit trail
  • event-gateway: Event bus abstraction (NATS/Kafka)

Future Phases: Platform Maturity​

Goal: Add advanced capabilities as products require them.

  • user-preferences-service: User settings (build when i18n needed)
  • developer-portal-bff: Self-service client registration (build for ecosystem)
  • Advanced IAM: Resource hierarchies, cross-account access (IaaS level)

3. What Was Archived​

The following services were archived as overengineered (split prematurely before understanding the problem):

  • policy-service - Consolidated into iam-service (ABAC attributes belong in authorization domain)
  • customization-service - Premature optimization (use JSONB metadata, add schemas when demand exists)
  • tenant-lifecycle-service - Just a status field (consolidated into iam-service)
  • onboarding-service - Replaced by workflow-driven pattern
  • payment-gateway-service - Not core platform yet (build when needed)

See: ADR-0052: IAM Consolidation Decision for rationale.

4. Product Progression Strategy​

SaaS (Current Target)​

  • Simple multi-tenant apps
  • RBAC sufficient (roles per tenant)
  • User auth in BFF layer
  • IAM: S2S only, simple token enrichment

PaaS (Future - Progressive Addition)​

  • Resource-level permissions
  • ABAC (attribute-based rules)
  • ReBAC (relationship-based: owner, editor, viewer)
  • Add permissions-service when needed

IaaS (Much Later - Progressive Addition)​

  • AWS/GCP-like IAM complexity
  • Policy documents, resource hierarchies
  • Cross-account access, federated identity
  • Add policy engine (OPA/Cedar) when needed

Key: Each level adds capabilities without refactoring previous levels.