# octaviofarinia/auth0_spring_boot_rest_api architecture

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

- Interactive diagram: https://gitdiagram.com/octaviofarinia/auth0_spring_boot_rest_api
- Repository: https://github.com/octaviofarinia/auth0_spring_boot_rest_api

## Overview

##### Project type and purpose
- Type: Backend-only REST API (Spring Boot “Resource Server”)
- Purpose: Expose public, client-scoped and admin-scoped endpoints, validating JWTs issued by Auth0.

##### Core components (to represent
a. External parties
– Clients (e.g. browser or mobile app)
– Auth0 (Identity Provider issuing JWTs, exposing JWKS endpoints)
b. Spring Boot Application
– Security Layer
- OAuth2 Resource-Server filter chain
- AudienceValidator
- SecurityConfiguration (defines URL-to-scope/role rules)
– Controllers
- PublicController (no auth required)
- ClientController (requires “read:messages” scope)
- AdminController (requires “admin” role)
c. Development/Test Harness
– Maven wrapper, pom.xml, unit tests under src/test

##### Relationships and data flows
1. Client requests token from Auth0 (not shown as part of this service, but can be annotated).
2. Client attaches JWT in Authorization header to API request.
3. Spring Security intercepts incoming HTTP request.
– Validates signature against Auth0’s JWKS URI
– AudienceValidator checks the “aud” claim
– SecurityConfiguration enforces required scopes or roles per endpoint
4. If valid, request passes to the appropriate Controller.
5. Controller executes business logic (currently simple responses) and returns JSON to client.

##### Architectural patterns and design principles
- OAuth2 Resource Server pattern (externalizing auth to Auth0)
- Layered design: Security → Controllers → (Services/Repositories)
- Centralized configuration via Spring’s @Configuration classes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actors
    Clients[(Clients)]:::external
    Auth0[(Auth0 Identity Provider)]:::external

    %% Spring Boot Application
    SpringApp["Auth0ApiApplication"]:::spring

    %% Security Layer
    subgraph "Security Layer"
        direction TB
        FilterChain["OAuth2 Resource-Server Filter Chain"]:::security
        AudienceValidator["AudienceValidator"]:::security
        SecurityConfig["SecurityConfiguration"]:::security
    end

    %% Controllers
    subgraph "Controllers"
        direction TB
        PublicController["PublicController"]:::controller
        ClientController["ClientController"]:::controller
        AdminController["AdminController"]:::controller
    end

    %% Config and Build
    ApplicationProps((application.properties)):::config
    MavenPOM[(pom.xml)]:::config
    TestSuite["Auth0ApiApplicationTests"]:::config

    %% Optional Database
    Database[(Optional Database)]:::db

    %% Data flows
    Clients -->|"HTTPS: Token Request"| Auth0
    Clients -->|"HTTPS: Bearer JWT"| SpringApp
    SpringApp --> FilterChain
    FilterChain --> AudienceValidator
    FilterChain --> SecurityConfig
    FilterChain -->|"Fetch JWKS (HTTPS)"| Auth0
    FilterChain -->|"Valid JWT, no auth required"| PublicController
    FilterChain -->|"Valid JWT, scope=read:messages"| ClientController
    FilterChain -->|"Valid JWT, role=admin"| AdminController
    PublicController -->|"Return JSON"| Clients
    ClientController -->|"Return JSON"| Clients
    AdminController -->|"Return JSON"| Clients

    %% Optional persistence flow
    PublicController --> Database
    ClientController --> Database
    AdminController --> Database

    %% Configuration connections
    SpringApp -.-> ApplicationProps
    SpringApp -.-> MavenPOM
    SpringApp -.-> TestSuite

    %% Click events
    click SpringApp "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/java/com/example/auth0api/Auth0ApiApplication.java"
    click SecurityConfig "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/java/com/example/auth0api/configuration/security/SecurityConfiguration.java"
    click AudienceValidator "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/java/com/example/auth0api/configuration/security/AudienceValidator.java"
    click PublicController "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/java/com/example/auth0api/controllers/PublicController.java"
    click ClientController "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/java/com/example/auth0api/controllers/ClientController.java"
    click AdminController "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/java/com/example/auth0api/controllers/AdminController.java"
    click ApplicationProps "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/main/resources/application.properties"
    click MavenPOM "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/pom.xml"
    click TestSuite "https://github.com/octaviofarinia/auth0_spring_boot_rest_api/blob/master/src/test/java/com/example/auth0api/Auth0ApiApplicationTests.java"

    %% Styles
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef spring fill:#98fb98,stroke:#333,stroke-width:1px
    classDef security fill:#90ee90,stroke:#333,stroke-width:1px
    classDef controller fill:#ffa07a,stroke:#333,stroke-width:1px
    classDef config fill:#f0e68c,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef db fill:#ffe4e1,stroke:#333,stroke-width:1px,shape:cylinder
```
