How dream-horizon-org/guardian works
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: RestVerticle.java Rest Verticle · service Auth Services · dao DAOs · config Config Services
Components 20
Runtime
Process bootstrap and Vert.x wiring
- Main · Starts the Java 17 service and boots Vert.x
src/main/java/com/dreamsportslabs/guardian/Main.java - Main Verticle · Installs app wiring and launches the REST layer
src/main/java/com/dreamsportslabs/guardian/verticle/MainVerticle.java - Rest Verticle · 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 · First-generation sign-in, passwordless, guest, refresh, and logout endpoints
src/main/java/com/dreamsportslabs/guardian/rest - Auth v2 · Second-generation auth flows including MFA and biometric endpoints
src/main/java/com/dreamsportslabs/guardian/rest/v2 - OIDC API · Authorize, token, discovery, JWKS, and userinfo boundary
src/main/java/com/dreamsportslabs/guardian/rest - Admin API · Tenant, client, scope, and provider configuration endpoints
src/main/java/com/dreamsportslabs/guardian/rest/config
Core Logic
Services and security orchestration
- Auth Services · Coordinates password, social, passwordless, guest, OTP, and MFA flows
src/main/java/com/dreamsportslabs/guardian/service - OIDC Services · Builds authorization codes, tokens, discovery documents, and JWKS
src/main/java/com/dreamsportslabs/guardian/service - Config Services · Resolves and manages tenant-scoped auth and provider configuration
src/main/java/com/dreamsportslabs/guardian/service/config - Security Core · Token signing, verification, public keys, and revocation state
src/main/java/com/dreamsportslabs/guardian/service - Guice Wiring · Creates the application injector and module bindings
src/main/java/com/dreamsportslabs/guardian/injection - Validation · Custom annotations and validators applied before business logic
src/main/java/com/dreamsportslabs/guardian/validation
Data Layer
Persistence, queries, caches, and models
- Caches · Tenant, scopes, revocation, and in-process HTTP caching
src/main/java/com/dreamsportslabs/guardian/cache - DAOs · Entity DAOs and SQL helpers for clients, tokens, sessions, consent, and config
src/main/java/com/dreamsportslabs/guardian/dao - Data 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 · Google and Facebook provider integrations isolated from core auth logic
src/main/java/com/dreamsportslabs/guardian/service/impl/idproviders - MySQL · Primary persistent store for auth, config, token, and changelog data
- Redis · Backing store for distributed runtime state and ephemeral data
- Mock Service · Development mock for OTP and communication-style external flows
mock.py
Connections 22
- 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