Architecture Overview

FerrisKey is built using modern software architectures principles to ensure maintainability, testability, and scalability. This section provides a comprehensive understanding of how the system is structured and how its components work together.

Hexagonal Architecture

FerrisKey follows the Hexagonal Architecture pattern (also known as Ports and Adapters), which provides clean separation of concerns makes the codebase highly modular and adaptable to change.

Core Principles

The hexagonale architectures organizes code into distinct layers with clear boundaries:

┌─────────────────────────────────────────────────────────┐
│                    Infrastructure                       │
│  ┌─────────────────────────────────────────────────┐    │
│  │                Application                      │    │
│  │  ┌─────────────────────────────────────────┐    │    │
│  │  │              Domain                     │    │    │
│  │  │  ┌─────────────────────────────────┐    │    │    │
│  │  │  │            Entities             │    │    │    │
│  │  │  └─────────────────────────────────┘    │    │    │
│  │  └─────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Layer Breakdown

Domain layer (/core/src/domain)

The innermost layer containing pure business logic with no external dependencies.

Key Components:

• Entities: Core business objects representing users, realms, roles, etc.
• Services: Business rules and operations that manipulate entities.
• Ports: Interfaces defining how the application interacts with external systems.
• Value Objects: Immutable objects representing concepts like credentials, tokens

Example DOmain Modules:

domain/
├── authentication/    # Authentication flows & logic
├── client/            # OAuth2/OIDC client management  
├── credential/        # Password, TOTP, WebAuthn handling
├── realm/             # Multi-tenant realm isolation
├── role/              # Role-based access control
├── user/              # User lifecycle management
├── trident/           # MFA & security scopes
├── seawatch/          # Audit logging & observability
├── webhook/           # Event-driven extensibility
└── jwt/               # Token generation & validation

Application Layer (/core/src/application)

Orchestrates domain services and defines use cases. Acts as a bridge between the domain and infrastructure.

Key Responsibilities:

• Coordinating multiple domain services
• Handling cross-cutting concerns (transactions, validation)
• Defining application-specific workflows
• Managing service dependencies through dependency injection

type RealmRepo = PostgresRealmRepository;
type ClientRepo = PostgresClientRepository;
type UserRepo = PostgresUserRepository;
type UserRoleRepo = PostgresUserRoleRepository;
type SecurityEventRepo = PostgresSecurityEventRepository;
type CredentialRepo = PostgresCredentialRepository;
type WebhookRepo = PostgresWebhookRepository;
type RedirectUriRepo = PostgresRedirectUriRepository;
type RoleRepo = PostgresRoleRepository;
type HealthCheckRepo = PostgresHealthCheckRepository;
type RecoveryCodeRepo = RandBytesRecoveryCodeRepository<10, Argon2HasherRepository>;
type AuthSessionRepo = PostgresAuthSessionRepository;
type HasherRepo = Argon2HasherRepository;
type UserRequiredActionRepo = PostgresUserRequiredActionRepository;
type KeystoreRepo = PostgresKeyStoreRepository;
type RefreshTokenRepo = PostgresRefreshTokenRepository;

#[derive(Clone)]
pub struct ApplicationService {
    pub(crate) security_event_service:
        SecurityEventServiceImpl<RealmRepo, UserRepo, ClientRepo, UserRoleRepo, SecurityEventRepo>,
    pub(crate) credential_service:
        CredentialServiceImpl<RealmRepo, UserRepo, ClientRepo, UserRoleRepo, CredentialRepo>,
    pub(crate) client_service: ClientServiceImpl<
        RealmRepo,
        UserRepo,
        ClientRepo,
        UserRoleRepo,
        WebhookRepo,
        RedirectUriRepo,
        RoleRepo,
        SecurityEventRepo,
    >,
    pub(crate) realm_service:
        RealmServiceImpl<RealmRepo, UserRepo, ClientRepo, UserRoleRepo, RoleRepo, WebhookRepo>,
}

Infrastructure Layer (/core/src/infrastructure)

Implements the ports defined by the domain layer, providing concrete adapters for external systems.

Key Components:

• Repositories: Database access implementations (e.g., PostgreSQL).
• External Services: HTTP clients, email providers, KMS integrations.
• Adapters: Concrete implementations of domain ports.
• Configuration: Database connections, messaging systems, etc.

Component Relationships

FerrisKey consists of several interconnected components that work together to provide a complete IAM solution:

Core Library (/core)

The heart of FerrisKey containing all business logic

Technologies:

• Rust with async/await for high performance
• SQLx for database interactions
• Tokio runtime for async execution

API Server (/api)

HTTP REST API exposing FerrisKey functionalities to clients.

Technologies:

• Axum web framework for high-performance HTTP handling.
• OpenAPI/Swagger documentation generation
• JWT for stateless authentication
• Prometheus metrics integration

Key Features:

• RESTful endpoints for all IAM operations
• OpenAPI specification generation
• Request validation and error handling
• CORS support for web applications
• Rate limiting and security headers

Web Console (/front)

Modern React application providing the administrative UI for FerrisKey.

Technologies:

• React with TypeScript for type safety
• Tailwind CSS for styling
• ShadCN UI components for consistent design
• React Query for data fetching and caching
• Zustand for state management

Key Features:

• Responsive admin dashboard
• Real-time updates using React Query
• Type-safe API integration
• Role-based access control in the UI
• Modular component architecture
• Feature flag system for experimental features

Kubernetes Operator (/operator)

CLoud-native deployment automation for Kubernetes environments.

Technologies:

• Rust with the Kube crate
• Custom Resource Definitions (CRDs) for FerrisKey
• Controller pattern for reconciliation loops
• Helm charts for easy deployment

Key Features:

• Automatic deployment and scaling
• Configuration management via CRDs
• Health monitoring and recovery
• Integration with existing Kubernetes ecosystems

Key Design Patterns

Repository Pattern

All data access goes through repository interfaces, making the system database-agnostic and easily testable.

Domain Layer:     trait UserRepository
                       ↓
Infrastructure:   PostgresUserRepository
                       ↓  
Database:         PostgreSQL with SeaORM

Service Layer Pattern

Business logic is encapsulated in service classes that orchestrate multiple repositories and domain objects.

Dependency Injection

Services receive their dependencies through constructor injection, enabling easy testing and loose coupling.

Event-Driven Architecture

Webhook system allows external systems to react to FerrisKey events without tight coupling.