# gustavoventieri/auth-api-sample architecture

> Architecture diagram of the GitHub repository gustavoventieri/auth-api-sample, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gustavoventieri/auth-api-sample
- Repository: https://github.com/gustavoventieri/auth-api-sample

## Overview

Auth API Sample is a Spring Boot authentication and authorization API with a framework-independent core. Its main flow is account registration, email OTP verification, mandatory TOTP setup, then two-step sign-in and cookie-based JWT/refresh-token sessions. It also supports session renewal and revocation, recovery codes, administrative MFA reset, RBAC, and email notifications. The graph follows README-documented capabilities and relationships visible in the supplied source excerpts; unsampled adapter wiring is not asserted beyond those documented links.

Main entry points: [`framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/MfaController.java`](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/MfaController.java) (MFA endpoints), [`framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/AuthController.java`](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/AuthController.java) (Auth endpoints), [`core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java`](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java) (Email verification), [`framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/SessionController.java`](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/SessionController.java) (Session endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP and security"]
  node_auth_http["Auth endpoints"]
  node_mfa_http["MFA endpoints<br/>[MfaController.java]"]
  node_session_http["Session endpoints"]
  node_security["Security and RBAC"]
end

subgraph group_identity["Identity lifecycle"]
  node_signup["Account signup<br/>[SignUpService.java]"]
  node_verify_email["Email verification"]
  node_user_domain["User state<br/>[UserDomain.java]"]
end

subgraph group_sessions["MFA and sessions"]
  node_mfa_setup["TOTP setup"]
  node_mfa_confirm["Confirm TOTP"]
  node_mfa_verify["MFA verification"]
  node_recovery["Recovery codes"]
  node_admin_reset["Admin MFA reset"]
  node_signin["Sign in<br/>[SignInService.java]"]
  node_issue_tokens["Issue tokens"]
  node_refresh["Rotate session"]
  node_signout["Sign out"]
end

subgraph group_infra["Infrastructure"]
  node_user_storage[("User persistence")]
  node_session_store[("Session and MFA storage")]
  node_jwt["JWT utilities"]
  node_email["Email delivery and templates<br/>[EmailAdapter.java]"]
end

node_client(("API client"))
node_email_service["Email provider"]
node_database[("PostgreSQL")]

node_client -->|"submits auth"| node_auth_http
node_client -->|"submits MFA"| node_mfa_http
node_client -->|"manages sessions"| node_session_http
node_auth_http -->|"invokes signup"| node_signup
node_auth_http -->|"invokes verification"| node_verify_email
node_auth_http -->|"invokes sign-in"| node_signin
node_mfa_http -->|"starts setup"| node_mfa_setup
node_mfa_http -->|"confirms setup"| node_mfa_confirm
node_mfa_http -->|"verifies code"| node_mfa_verify
node_mfa_http -->|"checks recovery"| node_recovery
node_mfa_http -->|"requests reset"| node_admin_reset
node_session_http -->|"renews session"| node_refresh
node_session_http -->|"revokes session"| node_signout
node_security -->|"protects routes"| node_auth_http
node_security -->|"authorizes roles"| node_mfa_http
node_signup -->|"persists account"| node_user_storage
node_verify_email -->|"verifies user"| node_user_domain
node_verify_email -->|"sends notice"| node_email
node_verify_email -->|"issues setup challenge"| node_mfa_setup
node_mfa_confirm -->|"issues session"| node_issue_tokens
node_mfa_confirm -->|"sends notice"| node_email
node_issue_tokens -->|"stores token hash"| node_session_store
node_issue_tokens -->|"generates access token"| node_jwt
node_refresh -->|"reads and revokes"| node_session_store
node_refresh -->|"generates access token"| node_jwt
node_session_store -->|"persists sessions"| node_database
node_user_storage -->|"persists users"| node_database
node_email -->|"delivers messages"| node_email_service

click node_auth_http "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/AuthController.java"
click node_mfa_http "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/MfaController.java"
click node_session_http "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/SessionController.java"
click node_security "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/shared/config/security/SecurityConfig.java"
click node_signup "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/SignUpService.java"
click node_verify_email "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java"
click node_user_domain "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/user/domain/UserDomain.java"
click node_user_storage "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/user/adapter/port/out/UserRepositoryAdapter.java"
click node_mfa_setup "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/SetupTotpService.java"
click node_mfa_confirm "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java"
click node_mfa_verify "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyTotpService.java"
click node_recovery "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyRecoveryCodeService.java"
click node_admin_reset "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/AdminResetMfaService.java"
click node_signin "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/SignInService.java"
click node_issue_tokens "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java"
click node_refresh "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java"
click node_signout "https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/SignOutService.java"
click node_session_store "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/out/persistence/RefreshTokenRepositoryAdapter.java"
click node_jwt "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/utils/jwt/JwtAccessTokenGenerator.java"
click node_email "https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/shared/email/EmailAdapter.java"

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_auth_http,node_mfa_http,node_session_http,node_security,node_client toneBlue
class node_signup,node_verify_email,node_user_domain,node_database toneAmber
class node_mfa_setup,node_mfa_confirm,node_mfa_verify,node_recovery,node_admin_reset,node_signin,node_issue_tokens,node_refresh,node_signout toneMint
class node_user_storage,node_session_store,node_jwt,node_email toneRose
class node_email_service toneIndigo
```

## Components

### HTTP and security

- [Auth endpoints](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/AuthController.java): `framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/AuthController.java`
- [MFA endpoints](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/MfaController.java): `framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/MfaController.java`
- [Session endpoints](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/SessionController.java): `framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/SessionController.java`
- [Security and RBAC](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/shared/config/security/SecurityConfig.java): `framework/src/main/java/com/auth/api/framework/shared/config/security/SecurityConfig.java`

### Identity lifecycle

- [Account signup](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/SignUpService.java): `core/src/main/java/com/auth/api/core/auth/application/service/sign/SignUpService.java`
- [Email verification](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java): `core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java`
- [User state](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/user/domain/UserDomain.java): `core/src/main/java/com/auth/api/core/user/domain/UserDomain.java`

### MFA and sessions

- [TOTP setup](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/SetupTotpService.java): `core/src/main/java/com/auth/api/core/auth/application/service/mfa/SetupTotpService.java`
- [Confirm TOTP](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java): `core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java`
- [MFA verification](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyTotpService.java): `core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyTotpService.java`
- [Recovery codes](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyRecoveryCodeService.java): `core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyRecoveryCodeService.java`
- [Admin MFA reset](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/mfa/AdminResetMfaService.java): `core/src/main/java/com/auth/api/core/auth/application/service/mfa/AdminResetMfaService.java`
- [Sign in](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/SignInService.java): `core/src/main/java/com/auth/api/core/auth/application/service/sign/SignInService.java`
- [Issue tokens](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java): `core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java`
- [Rotate session](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java): `core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java`
- [Sign out](https://github.com/gustavoventieri/auth-api-sample/blob/master/core/src/main/java/com/auth/api/core/auth/application/service/sign/SignOutService.java): `core/src/main/java/com/auth/api/core/auth/application/service/sign/SignOutService.java`

### Infrastructure

- [User persistence](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/user/adapter/port/out/UserRepositoryAdapter.java): `framework/src/main/java/com/auth/api/framework/user/adapter/port/out/UserRepositoryAdapter.java`
- [Session and MFA storage](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/adapter/port/out/persistence/RefreshTokenRepositoryAdapter.java): `framework/src/main/java/com/auth/api/framework/auth/adapter/port/out/persistence/RefreshTokenRepositoryAdapter.java`
- [JWT utilities](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/auth/utils/jwt/JwtAccessTokenGenerator.java): `framework/src/main/java/com/auth/api/framework/auth/utils/jwt/JwtAccessTokenGenerator.java`
- [Email delivery and templates](https://github.com/gustavoventieri/auth-api-sample/blob/master/framework/src/main/java/com/auth/api/framework/shared/email/EmailAdapter.java): `framework/src/main/java/com/auth/api/framework/shared/email/EmailAdapter.java`

### Other components

- **API client**
- **Email provider**
- **PostgreSQL**

## Connections

- API client → Auth endpoints: submits auth
- API client → MFA endpoints: submits MFA
- API client → Session endpoints: manages sessions
- Auth endpoints → Account signup: invokes signup
- Auth endpoints → Email verification: invokes verification
- Auth endpoints → Sign in: invokes sign-in
- MFA endpoints → TOTP setup: starts setup
- MFA endpoints → Confirm TOTP: confirms setup
- MFA endpoints → MFA verification: verifies code
- MFA endpoints → Recovery codes: checks recovery
- MFA endpoints → Admin MFA reset: requests reset
- Session endpoints → Rotate session: renews session
- Session endpoints → Sign out: revokes session
- Security and RBAC → Auth endpoints: protects routes
- Security and RBAC → MFA endpoints: authorizes roles
- Account signup → User persistence: persists account
- Email verification → User state: verifies user (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java`)
- Email verification → Email delivery and templates: sends notice (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java`)
- Email verification → TOTP setup: issues setup challenge (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java`)
- Confirm TOTP → Issue tokens: issues session (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java`)
- Confirm TOTP → Email delivery and templates: sends notice (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java`)
- Issue tokens → Session and MFA storage: stores token hash (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java`)
- Issue tokens → JWT utilities: generates access token (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java`)
- Rotate session → Session and MFA storage: reads and revokes (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java`)
- Rotate session → JWT utilities: generates access token (evidence: `core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java`)
- Session and MFA storage → PostgreSQL: persists sessions
- User persistence → PostgreSQL: persists users
- Email delivery and templates → Email provider: delivers messages