# dream-horizon-org/guardian architecture

> Architecture diagram of the GitHub repository dream-horizon-org/guardian, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dream-horizon-org/guardian
- Repository: https://github.com/dream-horizon-org/guardian

## Overview

1. Guardian is a single Java 17 service built on Vert.x. The runtime entrypoint is `Main`, which boots `MainVerticle` and `RestVerticle`. Dependency wiring is handled through Guice (`GuiceInjector`, `MainModule`), so the app is organized as a vertically layered service rather than a framework-heavy monolith.

2. The HTTP surface is split into clear API groups under `rest/`: core authentication, OAuth/OIDC, user/session management, admin/configuration, and health/JWKS/discovery endpoints. There are two generations of auth APIs (`rest/v1` and `rest/v2`), which is important for diagramming compatibility boundaries.

3. Request handling follows a simple pipeline: REST resource → service → DAO/query/model → storage or external call. DTOs are separated into request/response packages, and validation is enforced with custom annotations and validators before requests reach business logic.

4. The service layer is the main orchestration boundary. Services such as `AuthorizeService`, `OidcTokenService`, `RefreshToken`, `UserConsentService`, `Passwordless`, `SocialAuthService`, `MfaService`, and `UserInfoService` coordinate auth flows, token lifecycle, consent, and user/session state. Configuration-specific services live under `service/config` and manage tenant-scoped auth settings.

5. Persistence is centered on MySQL. The `dao` package contains entity-specific DAOs, query helpers, and data models for clients, scopes, tokens, revocations, user consent, credentials, sessions, and changelog/config data. Schema evolution is managed through SQL migrations and changelog resources, with `seed.sql` providing initial tenant/client/test data.

6. Multi-tenancy is a first-class boundary. Tenant and provider configuration are modeled explicitly in `config/tenant`, `dao/model/config`, `dao/config`, `service/config`, and `rest/config`. `TenantCache`, `DefaultClientScopesCache`, and `ConfigFilter` suggest that tenant context and config are resolved early in request processing and then reused downstream.

7. Guardian’s identity-provider responsibilities are built around token issuance and verification. `TokenIssuer`, `TokenVerifier`, `PublicKeysManager`, `Jwks`, `RsaKeyGeneration`, and the JWT verifier package handle signing keys, JWKS exposure, and token validation. Revocation state is tracked separately through revocation-related services, DAOs, and cache layers.

8. The product supports several auth modalities that share the same core session/token system: username/password, passwordless, social login via Google/Facebook, guest login, OTP/contact verification, and MFA/biometric flows. These are implemented as distinct REST endpoints but converge on the same user, token, and tenant configuration model.

9. External integrations are intentionally isolated. Social login provider logic lives in `service/impl/idproviders`, and the readme plus `mock.py` indicate a mock integration service used in local development for OTP/communication flows. The `integrations.yaml` OpenAPI file defines the contracts that outside user/communication systems must implement.

10. Redis and Caffeine are both part of the runtime architecture. The repository includes `RedisConfig` and a `rest/CaffeineCache` component, indicating a mix of shared cache/state backing and in-process caching. This matters for diagramming because some lookup paths are optimized locally while other ephemeral state is expected to survive beyond a single JVM.

11. Error handling and protocol correctness are centralized. Custom exception mappers translate validation, domain, and web exceptions into consistent API responses, while resource-specific enums and constants encode OAuth/OIDC and auth-flow semantics. That makes the API boundary stable even though the underlying flows are fairly complex.

12. Operationally, the repo is designed for Docker-first deployment. `docker-compose.yaml`, `Dockerfile`, `Dockerfile-mock`, and `quick-start.sh` start Guardian alongside MySQL, Redis, and the mock service. For an architecture diagram, the main external boxes are the client applications, MySQL, Redis, and the mock/integration service, with Guardian in the middle as the authorization server and identity broker.

Main entry points: [`src/main/java/com/dreamsportslabs/guardian/verticle/RestVerticle.java`](https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/verticle/RestVerticle.java) (Rest Verticle), [`src/main/java/com/dreamsportslabs/guardian/service`](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service) (Auth Services), [`src/main/java/com/dreamsportslabs/guardian/dao`](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/dao) (DAOs), [`src/main/java/com/dreamsportslabs/guardian/service/config`](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service/config) (Config Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>java entrypoint<br/>[Main.java]"]
  node_main_verticle["Main Verticle<br/>vertx bootstrap<br/>[MainVerticle.java]"]
  node_rest_verticle["Rest Verticle<br/>http runtime<br/>[RestVerticle.java]"]
end

subgraph group_api["HTTP API"]
  node_auth_v1["Auth v1<br/>legacy auth api"]
  node_auth_v2["Auth v2<br/>current auth api"]
  node_oidc_api["OIDC API<br/>oidc endpoints"]
  node_admin_api["Admin API<br/>admin/config api"]
end

subgraph group_core["Core Logic"]
  node_core_auth["Auth Services<br/>auth orchestration"]
  node_oidc_core["OIDC Services<br/>token and discovery"]
  node_config_core["Config Services<br/>tenant config"]
  node_security_core["Security Core<br/>keys and revocation"]
  node_di["Guice Wiring<br/>dependency injection"]
  node_validation{{"Validation<br/>request guards"}}
end

subgraph group_data["Data Layer"]
  node_cache(("Caches<br/>runtime cache"))
  node_dao[("DAOs<br/>mysql persistence")]
  node_models["Data Models<br/>persistence models"]
end

subgraph group_infra["Infrastructure"]
  node_external_idp["External IdPs<br/>social providers"]
  node_mysql[("MySQL<br/>database")]
  node_redis[("Redis<br/>shared cache")]
  node_mock_integration["Mock Service<br/>local integration<br/>[mock.py]"]
end

node_main -->|"boots"| node_main_verticle
node_main_verticle -->|"launches"| node_rest_verticle
node_di -->|"wires"| node_main_verticle
node_rest_verticle -->|"routes"| node_auth_v1
node_rest_verticle -->|"routes"| node_auth_v2
node_rest_verticle -->|"routes"| node_oidc_api
node_rest_verticle -->|"routes"| node_admin_api
node_auth_v1 -->|"calls"| node_core_auth
node_auth_v2 -->|"calls"| node_core_auth
node_oidc_api -->|"calls"| node_oidc_core
node_admin_api -->|"calls"| node_config_core
node_core_auth -->|"reads/writes"| node_dao
node_oidc_core -->|"uses"| node_security_core
node_security_core -->|"reads/writes"| node_dao
node_config_core -->|"uses"| node_cache
node_config_core -->|"reads/writes"| node_dao
node_dao -->|"persists"| node_mysql
node_cache -->|"backs onto"| node_redis
node_validation -->|"guards"| node_auth_v2
node_validation -->|"guards"| node_auth_v1
node_core_auth -->|"integrates"| node_external_idp
node_external_idp -.->|"dev flow"| node_mock_integration

click node_main "https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/Main.java"
click node_main_verticle "https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/verticle/MainVerticle.java"
click node_rest_verticle "https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/verticle/RestVerticle.java"
click node_auth_v1 "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest"
click node_auth_v2 "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest/v2"
click node_oidc_api "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest"
click node_admin_api "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest/config"
click node_core_auth "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service"
click node_oidc_core "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service"
click node_config_core "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service/config"
click node_security_core "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service"
click node_di "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/injection"
click node_cache "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/cache"
click node_dao "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/dao"
click node_models "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/dao/model"
click node_validation "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/validation"
click node_external_idp "https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service/impl/idproviders"
click node_mock_integration "https://github.com/dream-horizon-org/guardian/blob/main/mock.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_main_verticle,node_rest_verticle toneBlue
class node_auth_v1,node_auth_v2,node_oidc_api,node_admin_api toneAmber
class node_core_auth,node_oidc_core,node_config_core,node_security_core,node_di,node_validation toneMint
class node_cache,node_dao,node_models toneRose
class node_external_idp,node_mysql,node_redis,node_mock_integration toneIndigo
```

## Components

### Runtime

Process bootstrap and Vert.x wiring

- [Main](https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/Main.java): java entrypoint · Starts the Java 17 service and boots Vert.x · `src/main/java/com/dreamsportslabs/guardian/Main.java`
- [Main Verticle](https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/verticle/MainVerticle.java): vertx bootstrap · Installs app wiring and launches the REST layer · `src/main/java/com/dreamsportslabs/guardian/verticle/MainVerticle.java`
- [Rest Verticle](https://github.com/dream-horizon-org/guardian/blob/main/src/main/java/com/dreamsportslabs/guardian/verticle/RestVerticle.java): http runtime · Hosts the HTTP resources and request pipeline · `src/main/java/com/dreamsportslabs/guardian/verticle/RestVerticle.java`

### HTTP API

REST surface split by auth, OIDC, and config

- [Auth v1](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest): legacy auth api · First-generation sign-in, passwordless, guest, refresh, and logout endpoints · `src/main/java/com/dreamsportslabs/guardian/rest`
- [Auth v2](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest/v2): current auth api · Second-generation auth flows including MFA and biometric endpoints · `src/main/java/com/dreamsportslabs/guardian/rest/v2`
- [OIDC API](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest): oidc endpoints · Authorize, token, discovery, JWKS, and userinfo boundary · `src/main/java/com/dreamsportslabs/guardian/rest`
- [Admin API](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/rest/config): admin/config api · Tenant, client, scope, and provider configuration endpoints · `src/main/java/com/dreamsportslabs/guardian/rest/config`

### Core Logic

Services and security orchestration

- [Auth Services](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service): auth orchestration · Coordinates password, social, passwordless, guest, OTP, and MFA flows · `src/main/java/com/dreamsportslabs/guardian/service`
- [OIDC Services](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service): token and discovery · Builds authorization codes, tokens, discovery documents, and JWKS · `src/main/java/com/dreamsportslabs/guardian/service`
- [Config Services](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service/config): tenant config · Resolves and manages tenant-scoped auth and provider configuration · `src/main/java/com/dreamsportslabs/guardian/service/config`
- [Security Core](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service): keys and revocation · Token signing, verification, public keys, and revocation state · `src/main/java/com/dreamsportslabs/guardian/service`
- [Guice Wiring](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/injection): dependency injection · Creates the application injector and module bindings · `src/main/java/com/dreamsportslabs/guardian/injection`
- [Validation](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/validation): request guards · Custom annotations and validators applied before business logic · `src/main/java/com/dreamsportslabs/guardian/validation`

### Data Layer

Persistence, queries, caches, and models

- [Caches](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/cache): runtime cache · Tenant, scopes, revocation, and in-process HTTP caching · `src/main/java/com/dreamsportslabs/guardian/cache`
- [DAOs](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/dao): mysql persistence · Entity DAOs and SQL helpers for clients, tokens, sessions, consent, and config · `src/main/java/com/dreamsportslabs/guardian/dao`
- [Data Models](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/dao/model): persistence models · DAO models and config models used across storage and services · `src/main/java/com/dreamsportslabs/guardian/dao/model`

### Infrastructure

Deployment and external runtime dependencies

- [External IdPs](https://github.com/dream-horizon-org/guardian/tree/main/src/main/java/com/dreamsportslabs/guardian/service/impl/idproviders): social providers · Google and Facebook provider integrations isolated from core auth logic · `src/main/java/com/dreamsportslabs/guardian/service/impl/idproviders`
- **MySQL**: database · Primary persistent store for auth, config, token, and changelog data
- **Redis**: shared cache · Backing store for distributed runtime state and ephemeral data
- [Mock Service](https://github.com/dream-horizon-org/guardian/blob/main/mock.py): local integration · Development mock for OTP and communication-style external flows · `mock.py`

## Connections

- Main → Main Verticle: boots · Main starts the application verticle
- Main Verticle → Rest Verticle: launches · Main verticle starts the REST verticle
- Guice Wiring → Main Verticle: wires · Guice provides dependencies for runtime components
- Rest Verticle → Auth v1: routes · REST verticle exposes legacy auth endpoints
- Rest Verticle → Auth v2: routes · REST verticle exposes v2 auth endpoints
- Rest Verticle → OIDC API: routes · REST verticle exposes OIDC and identity-provider endpoints
- Rest Verticle → Admin API: routes · REST verticle exposes tenant and config endpoints
- Auth v1 → Auth Services: calls · v1 auth resources delegate to orchestration services
- Auth v2 → Auth Services: calls · v2 auth resources delegate to orchestration services
- OIDC API → OIDC Services: calls · OIDC endpoints delegate to token and discovery services
- Admin API → Config Services: calls · Config endpoints delegate to tenant-scoped config services
- Auth Services → DAOs: reads/writes · Auth flows persist sessions, credentials, consent, and tokens
- OIDC Services → Security Core: uses · OIDC flows depend on signing, verification, and key management
- Security Core → DAOs: reads/writes · Key and revocation state is stored through persistence
- Config Services → Caches: uses · Tenant and config lookups are cached early in request handling
- Config Services → DAOs: reads/writes · Configuration services persist tenant and provider settings
- DAOs → MySQL: persists · Primary storage for repository data
- Caches → Redis: backs onto · Shared state may be distributed through Redis
- Validation → Auth v2: guards · Custom validators protect complex v2 auth requests
- Validation → Auth v1: guards · Request validation also applies to selected legacy endpoints
- Auth Services → External IdPs: integrates · Social auth services call provider-specific implementations
- External IdPs → Mock Service: dev flow · Local development uses a mock integration service for external communication flows