Skip to main content

Service Breakdown & Architecture

NOTE: This document reflects the current platform service organization as of 2025-11.

Platform vs Product​

Citadel is a platform of reusable primitives, not a product with domain logic.

Platform Services (Unix Commands)​

Core cross-cutting services that form the composable foundation:

P0 - Foundation:

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

P1 - Core:

  • 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 - OAuth2 client management router
  • permissions-service - ReBAC engine (SpiceDB, if needed)

P2 - Essential:

  • notification-service - Multi-channel notifications
  • audit-service - Compliance audit trail
  • event-gateway - Event bus abstraction

Future:

  • user-preferences-service - User settings & preferences
  • developer-portal-bff - Self-service client registration

Archived Services​

Services in notes/checklists/archived/ include:

  • ERP-specific (invoicing, stock, tax, warehouse, accounts master, products master)
  • Product-specific (will be built as proprietary products on the platform)
  • Premature (search, reporting, ETL - build when pattern emerges)
  • Overengineered (policy-service, customization-service, tenant-lifecycle-service) - consolidated into iam-service

Design Philosophy​

"Microservices as Unix Commands"

  • Each service does one thing well
  • Services compose via pipes (workflows, events)
  • Products are "shell scripts" orchestrating platform primitives

When to add a platform service:

  • ✅ Cross-cutting concern (IAM, workflows, notifications)
  • ✅ Reusable primitive (ledger, policy engine, permissions graph)
  • ✅ Single responsibility
  • ✅ Multiple use cases across products

When to build as product service:

  • ❌ Domain-specific business logic
  • ❌ Industry-specific workflows
  • ❌ Product-specific schemas

Documentation Organization​

Master Roadmap: See ROADMAP.md in repository root for sprint-based implementation plan

Service Checklists: Detailed per-service implementation checklists are in notes/checklists/platform/

Service Documentation: Individual service docs are in this documentation site under the Services section