Skip to main content

Introduction to Citadel

Welcome to the official documentation for Citadel, a modern, composable, open-source microservices platform.

What is Citadel?​

Citadel is a collection of reusable microservices primitives designed to help technology companies rapidly build and operate SaaS products for non-technical industries.

Key Features:

  • IdP Abstraction: It provides an abstraction over Identity Providers (IdP) that does not store PII, allowing for flexible and secure identity management.
  • Complex Authorization: Includes a sophisticated policy engine (ABAC/RBAC) and a fine-grained permissions system (ReBAC) with built-in multi-tenancy support.
  • Composable Primitives: Essential cross-cutting services (workflows, ledgers, notifications) that can be composed into industry-specific applications.

Philosophy: Citadel services are like Unix commands - small, focused, composable primitives that do one thing well. Your products are shell scripts that pipe these commands together for specific business cases.

The project is architected as a collection of independent microservices that communicate asynchronously. This approach, guided by Domain-Driven Design (DDD), promotes loose coupling and enables teams to develop, deploy, and scale services autonomously.

How to Use These Docs​

This documentation is structured to serve different roles. Here’s a guide to help you find what you need:

For Everyone​

  • Project Overview: Start here to understand the vision, guiding principles, and high-level goals of the Citadel platform.

For Architects & Tech Leads​

  • Architecture: This section contains the core architectural documentation, including the System Overview and, most importantly, the Architectural Decision Records (ADRs) which document the rationale behind key technical choices.

For Developers​

  • Services: Dive deep into the documentation for individual microservices, including their specific design, API contracts, and ADRs.
  • Guides & Tutorials: Find practical, step-by-step instructions for common tasks, such as setting up your environment or implementing core workflows.
  • Contributing: If you plan to write code, this is a must-read. It covers our development process, coding standards, and more.

For Operators & SREs​

  • Operations: This section contains operational runbooks, deployment guides, and monitoring procedures for maintaining the platform in production.