# micronaut-projects/micronaut-security architecture

> Architecture diagram of the GitHub repository micronaut-projects/micronaut-security, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/micronaut-projects/micronaut-security
- Repository: https://github.com/micronaut-projects/micronaut-security

## Overview

##### Project Type and Purpose
- This is a multi‐module, open‐source security framework for the Micronaut JVM platform.
- It provides pluggable security capabilities—core authentication/authorization, JWT, OAuth2, CSRF, LDAP, session support, AOT code generation, and annotations.

##### High-Level Architecture (Components)
A. Core Module (“security”)
- Contains the central filter chain, authentication providers, handlers, rules, configuration properties, converters, and events.
B. Annotation Module (“security-annotations”)
- Provides compile-time annotation mappings and visitor infrastructure.
C. AOT Module (“security-aot”)
- Generates ahead-of-time code for optimized metadata and provider wiring.
D. Feature Modules
1. security-csrf – CSRF token lifecycle (generators, filters, resolvers, validators)
2. security-jwt  – JWT support (config, encryption, signature, parsing, validation, endpoints)
3. security-oauth2 – OAuth2/OpenID Connect client endpoints, state management, flows, token endpoints
4. security-ldap – LDAP‐backed authentication provider
5. security-session – HTTP session‐based authentication
E. BOM Module (“security-bom”)
- Centralized dependency management for all modules.
F. Documentation & Guides (src/main/docs)
G. Test Suites / Examples
- End-to-end and integration tests (test-suite-*), sample auth server and clients.

##### Relationships and Dependencies
- All feature modules depend on the Core module and the Annotations module.
- The AOT module depends on Core and feature modules to generate code for each feature.
- The BOM module aggregates versions of Core, Annotations, AOT, and feature modules.
- Documentation sits outside code modules but refers to each feature.
- Test suites pull in combinations of modules to exercise flows (e.g., JWT, OAuth2).
- Build system: Gradle with GitHub Actions pipelines invoking snapshots, releases, AOT builds.

##### Architectural Patterns & Principles
- Modular design—each feature in its own Gradle subproject, clean separation.
- Pluggable filter chain—Core defines AuthenticationFetcher, SecurityFilter, with feature modules providing implementations.
- Factory/Condition pattern—conditional beans and factories enable or disable features at runtime via config.
- Ahead-Of-Time code generation for Graal and performance optimizations.
- Annotation processors to reduce reflection and support native images.

##### Detail and Extensibility Points
- Extension points in Core (AuthenticationProvider, SecurityRule).
- How feature modules register implementations via META-INF/services (annotation consumers).
- AOT code generators discovering services and producing “GeneratedFile” outputs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Modules
    subgraph "Core & Annotation Modules"
        direction TB
        security["security"]:::core
        security_annotations["security-annotations"]:::annotations
    end

    subgraph "AOT Module"
        direction TB
        security_aot["security-aot"]:::aot
    end

    subgraph "Feature Modules"
        direction TB
        security_csrf["security-csrf"]:::feature
        security_jwt["security-jwt"]:::feature
        security_oauth2["security-oauth2"]:::feature
        security_ldap["security-ldap"]:::feature
        security_session["security-session"]:::feature
    end

    subgraph "BOM & Docs"
        direction TB
        security_bom["security-bom"]:::bom
        docs["Documentation & Guides"]:::docs
    end

    subgraph "Test Suites & Examples"
        direction TB
        tests["test-suite*"]:::tests
    end

    micronaut_app["Micronaut App"]:::consumer
    cicd["CI/CD Pipeline"]:::ci

    %% Dependencies
    security_csrf -->|"depends on"| security
    security_jwt -->|"depends on"| security
    security_oauth2 -->|"depends on"| security
    security_ldap -->|"depends on"| security
    security_session -->|"depends on"| security

    security_csrf -->|"depends on"| security_annotations
    security_jwt -->|"depends on"| security_annotations
    security_oauth2 -->|"depends on"| security_annotations
    security_ldap -->|"depends on"| security_annotations
    security_session -->|"depends on"| security_annotations

    security_aot -->|"depends on"| security
    security_aot -->|"generates code for"| security_csrf
    security_aot -->|"generates code for"| security_jwt
    security_aot -->|"generates code for"| security_oauth2
    security_aot -->|"generates code for"| security_ldap
    security_aot -->|"generates code for"| security_session
    security_aot -->|"depends on"| security_annotations

    security_bom -->|"aggregates versions"| security
    security_bom -->|"aggregates versions"| security_annotations
    security_bom -->|"aggregates versions"| security_aot
    security_bom -->|"aggregates versions"| security_csrf
    security_bom -->|"aggregates versions"| security_jwt
    security_bom -->|"aggregates versions"| security_oauth2
    security_bom -->|"aggregates versions"| security_ldap
    security_bom -->|"aggregates versions"| security_session

    micronaut_app -->|"includes BOM"| security_bom
    tests -->|"exercises flows with"| security
    tests -->|"exercises flows with"| security_csrf
    tests -->|"exercises flows with"| security_jwt
    tests -->|"exercises flows with"| security_oauth2
    tests -->|"exercises flows with"| security_ldap
    tests -->|"exercises flows with"| security_session

    cicd -->|"builds & releases"| security
    cicd -->|"builds & releases"| security_csrf
    cicd -->|"builds & releases"| security_jwt
    cicd -->|"builds & releases"| security_oauth2
    cicd -->|"builds & releases"| security_ldap
    cicd -->|"builds & releases"| security_session
    cicd -->|"builds & releases"| security_aot
    cicd -->|"builds & releases"| security_bom

    %% Click Events
    click security "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security/"
    click security_annotations "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-annotations/"
    click security_aot "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-aot/"
    click security_csrf "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-csrf/"
    click security_jwt "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-jwt/"
    click security_oauth2 "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-oauth2/"
    click security_ldap "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-ldap/"
    click security_session "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-session/"
    click security_bom "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/security-bom/"
    click docs "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/src/main/docs/"
    click tests "https://github.com/micronaut-projects/micronaut-security/tree/4.12.x/test-suite/"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px
    classDef annotations fill:#E3F2FD,stroke:#64B5F6,stroke-width:2px
    classDef aot fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
    classDef feature fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px
    classDef bom fill:#CFD8DC,stroke:#546E7A,stroke-width:2px
    classDef docs fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px
    classDef tests fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px
    classDef consumer fill:#B2EBF2,stroke:#0097A7,stroke-width:2px
    classDef ci fill:#F5F5F5,stroke:#757575,stroke-width:2px,stroke-dasharray: 5 5
```
