# groove-net/authservice architecture

> Architecture diagram of the GitHub repository groove-net/authservice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/groove-net/authservice
- Repository: https://github.com/groove-net/authservice

## Overview

AuthService provides registration, email confirmation, password login, MFA enrollment and verification, recovery-code use, and account-management use cases, exposed through REST endpoints and an AuthComponent gateway. Login validates input, loads the user, checks lockout and password state, persists login-attempt changes, then either returns success or issues a short-lived MFA challenge. The domain owns password and MFA rules; repositories and the unit of work persist state, while email and challenge services provide supporting integrations. README-only claims such as JWT/session handling and password-reset flows are not mapped as implemented components because the supplied tree does not show their source.

Main entry points: [`src/Auth/WebAPI.REST/Endpoints/auth`](https://github.com/groove-net/authservice/tree/main/src/Auth/WebAPI.REST/Endpoints/auth) (REST endpoints), [`src/Auth/AuthComponent.cs`](https://github.com/groove-net/authservice/blob/main/src/Auth/AuthComponent.cs) (Auth gateway), [`src/Auth/Application/UseCases/UserLogin.cs`](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/UserLogin.cs) (User login), [`src/Auth/Infrastructure/AuthDb/AuthDbContext.cs`](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/AuthDbContext.cs) (Unit of work)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Entry points"]
  node_rest["REST endpoints<br/>[auth]"]
  node_component["Auth gateway<br/>[AuthComponent.cs]"]
end

subgraph group_application["Application workflows"]
  node_register["Register user<br/>[RegisterUser.cs]"]
  node_confirm_email["Confirm email<br/>[ConfirmEmail.cs]"]
  node_send_confirmation["Send confirmation"]
  node_login["User login<br/>[UserLogin.cs]"]
  node_setup_mfa["Set up MFA<br/>[Setup2fa.cs]"]
  node_confirm_mfa["Confirm MFA<br/>[Confirm2fa.cs]"]
  node_verify_mfa["Verify MFA<br/>[Verify2fa.cs]"]
  node_recovery_code["Use recovery code<br/>[UseRecoveryCode.cs]"]
  node_disable_mfa["Disable MFA<br/>[Disable2fa.cs]"]
  node_pruner["Token pruning task"]
end

subgraph group_domain["Identity domain"]
  node_user["User aggregate<br/>[User.cs]"]
  node_repository_contract["User repository contract<br/>[IUserRepository.cs]"]
end

subgraph group_infrastructure["Persistence and integrations"]
  node_repository["User repository<br/>[UserRepository.cs]"]
  node_database[("Auth database<br/>[AuthDbContext.cs]")]
  node_challenge["MFA challenge"]
  node_secret_protector["Secret protection<br/>[AuthComponent.cs]"]
  node_email_sender["SMTP sender<br/>[SmtpEmailSender.cs]"]
  node_unit_of_work["Unit of work<br/>[AuthDbContext.cs]"]
  node_dispatcher["Domain event dispatcher"]
end

node_client(("Client"))
node_smtp(("SMTP service"))

node_client -->|"sends requests"| node_rest
node_client -.->|"calls gateway"| node_component
node_rest -->|"dispatches"| node_register
node_rest -->|"dispatches"| node_confirm_email
node_rest -->|"dispatches"| node_send_confirmation
node_rest -->|"dispatches"| node_login
node_rest -->|"dispatches"| node_setup_mfa
node_rest -->|"dispatches"| node_confirm_mfa
node_rest -->|"dispatches"| node_verify_mfa
node_rest -->|"dispatches"| node_recovery_code
node_rest -->|"dispatches"| node_disable_mfa
node_component -.->|"invokes"| node_register
node_component -.->|"invokes"| node_confirm_email
node_component -.->|"invokes"| node_send_confirmation
node_component -.->|"invokes"| node_login
node_component -.->|"invokes"| node_setup_mfa
node_component -.->|"invokes"| node_confirm_mfa
node_component -.->|"invokes"| node_verify_mfa
node_component -.->|"invokes"| node_recovery_code
node_component -.->|"invokes"| node_disable_mfa
node_login -->|"loads user"| node_repository_contract
node_repository -->|"implements"| node_repository_contract
node_repository -->|"queries and writes"| node_database
node_login -->|"checks credentials"| node_user
node_login -->|"saves changes"| node_unit_of_work
node_login -->|"creates challenge"| node_challenge
node_challenge -->|"protects token"| node_secret_protector
node_unit_of_work -->|"dispatches events"| node_dispatcher
node_unit_of_work -->|"commits changes"| node_database
node_email_sender -->|"sends mail"| node_smtp
node_pruner -->|"prunes tokens"| node_repository_contract

click node_rest "https://github.com/groove-net/authservice/tree/main/src/Auth/WebAPI.REST/Endpoints/auth"
click node_component "https://github.com/groove-net/authservice/blob/main/src/Auth/AuthComponent.cs"
click node_register "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/RegisterUser.cs"
click node_confirm_email "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/ConfirmEmail.cs"
click node_send_confirmation "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/SendEmailConfirmation.cs"
click node_login "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/UserLogin.cs"
click node_setup_mfa "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Setup2fa.cs"
click node_confirm_mfa "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Confirm2fa.cs"
click node_verify_mfa "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Verify2fa.cs"
click node_recovery_code "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/UseRecoveryCode.cs"
click node_disable_mfa "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Disable2fa.cs"
click node_user "https://github.com/groove-net/authservice/blob/main/src/Auth/Domain/Aggregates/UserAggregate/User.cs"
click node_repository_contract "https://github.com/groove-net/authservice/blob/main/src/Auth/Domain/Aggregates/UserAggregate/IUserRepository.cs"
click node_repository "https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/Repositories/UserRepository.cs"
click node_database "https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/AuthDbContext.cs"
click node_challenge "https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/TwoFactorChallenge/TwoFactorChallenge.cs"
click node_secret_protector "https://github.com/groove-net/authservice/blob/main/src/Auth/AuthComponent.cs"
click node_email_sender "https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/EmailSender/SmtpEmailSender.cs"
click node_unit_of_work "https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/AuthDbContext.cs"
click node_dispatcher "https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/DomainEventDispatcher.cs"
click node_pruner "https://github.com/groove-net/authservice/blob/main/src/Auth/Application/BackgroundTasks/PruneExpiredTokens.cs"

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_rest,node_component,node_client toneBlue
class node_register,node_confirm_email,node_send_confirmation,node_login,node_setup_mfa,node_confirm_mfa,node_verify_mfa,node_recovery_code,node_disable_mfa,node_pruner toneAmber
class node_user,node_repository_contract toneMint
class node_repository,node_database,node_challenge,node_secret_protector,node_email_sender,node_unit_of_work,node_dispatcher toneRose
class node_smtp toneIndigo
```

## Components

### Entry points

- [REST endpoints](https://github.com/groove-net/authservice/tree/main/src/Auth/WebAPI.REST/Endpoints/auth): `src/Auth/WebAPI.REST/Endpoints/auth`
- [Auth gateway](https://github.com/groove-net/authservice/blob/main/src/Auth/AuthComponent.cs): `src/Auth/AuthComponent.cs`

### Application workflows

- [Register user](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/RegisterUser.cs): `src/Auth/Application/UseCases/RegisterUser.cs`
- [Confirm email](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/ConfirmEmail.cs): `src/Auth/Application/UseCases/ConfirmEmail.cs`
- [Send confirmation](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/SendEmailConfirmation.cs): `src/Auth/Application/UseCases/SendEmailConfirmation.cs`
- [User login](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/UserLogin.cs): `src/Auth/Application/UseCases/UserLogin.cs`
- [Set up MFA](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Setup2fa.cs): `src/Auth/Application/UseCases/Setup2fa.cs`
- [Confirm MFA](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Confirm2fa.cs): `src/Auth/Application/UseCases/Confirm2fa.cs`
- [Verify MFA](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Verify2fa.cs): `src/Auth/Application/UseCases/Verify2fa.cs`
- [Use recovery code](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/UseRecoveryCode.cs): `src/Auth/Application/UseCases/UseRecoveryCode.cs`
- [Disable MFA](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/UseCases/Disable2fa.cs): `src/Auth/Application/UseCases/Disable2fa.cs`
- [Token pruning task](https://github.com/groove-net/authservice/blob/main/src/Auth/Application/BackgroundTasks/PruneExpiredTokens.cs): `src/Auth/Application/BackgroundTasks/PruneExpiredTokens.cs`

### Identity domain

- [User aggregate](https://github.com/groove-net/authservice/blob/main/src/Auth/Domain/Aggregates/UserAggregate/User.cs): `src/Auth/Domain/Aggregates/UserAggregate/User.cs`
- [User repository contract](https://github.com/groove-net/authservice/blob/main/src/Auth/Domain/Aggregates/UserAggregate/IUserRepository.cs): `src/Auth/Domain/Aggregates/UserAggregate/IUserRepository.cs`

### Persistence and integrations

- [User repository](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/Repositories/UserRepository.cs): `src/Auth/Infrastructure/AuthDb/Repositories/UserRepository.cs`
- [Auth database](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/AuthDbContext.cs): `src/Auth/Infrastructure/AuthDb/AuthDbContext.cs`
- [MFA challenge](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/TwoFactorChallenge/TwoFactorChallenge.cs): `src/Auth/Infrastructure/TwoFactorChallenge/TwoFactorChallenge.cs`
- [Secret protection](https://github.com/groove-net/authservice/blob/main/src/Auth/AuthComponent.cs): `src/Auth/AuthComponent.cs`
- [SMTP sender](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/EmailSender/SmtpEmailSender.cs): `src/Auth/Infrastructure/EmailSender/SmtpEmailSender.cs`
- [Unit of work](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/AuthDbContext.cs): `src/Auth/Infrastructure/AuthDb/AuthDbContext.cs`
- [Domain event dispatcher](https://github.com/groove-net/authservice/blob/main/src/Auth/Infrastructure/AuthDb/DomainEventDispatcher.cs): `src/Auth/Infrastructure/AuthDb/DomainEventDispatcher.cs`

### Other components

- **Client**
- **SMTP service**

## Connections

- Client → REST endpoints: sends requests
- Client → Auth gateway: calls gateway
- REST endpoints → Register user: dispatches
- REST endpoints → Confirm email: dispatches
- REST endpoints → Send confirmation: dispatches
- REST endpoints → User login: dispatches
- REST endpoints → Set up MFA: dispatches
- REST endpoints → Confirm MFA: dispatches
- REST endpoints → Verify MFA: dispatches
- REST endpoints → Use recovery code: dispatches
- REST endpoints → Disable MFA: dispatches
- Auth gateway → Register user: invokes
- Auth gateway → Confirm email: invokes
- Auth gateway → Send confirmation: invokes
- Auth gateway → User login: invokes
- Auth gateway → Set up MFA: invokes
- Auth gateway → Confirm MFA: invokes
- Auth gateway → Verify MFA: invokes
- Auth gateway → Use recovery code: invokes
- Auth gateway → Disable MFA: invokes
- User login → User repository contract: loads user
- User repository → User repository contract: implements
- User repository → Auth database: queries and writes
- User login → User aggregate: checks credentials
- User login → Unit of work: saves changes
- User login → MFA challenge: creates challenge
- MFA challenge → Secret protection: protects token
- Unit of work → Domain event dispatcher: dispatches events
- Unit of work → Auth database: commits changes
- SMTP sender → SMTP service: sends mail
- Token pruning task → User repository contract: prunes tokens