# endurannsu/auth architecture

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

- Interactive diagram: https://gitdiagram.com/endurannsu/auth
- Repository: https://github.com/endurannsu/auth

## Overview

This repository is an HTTP authentication service. Clients send registration, login, token refresh/logout, password-reset, and access-token validation requests; handlers pass them to the service, which applies authentication rules and uses repository interfaces backed by PostgreSQL. The server assembly wires these layers and starts the HTTP listener. Password recovery is implemented as OTP generation and confirmation. The README gives no further capability details; relationships shown here are based on the sampled source, so unsampled integrations and finer routing behavior are not inferred.

Main entry points: [`internal/app/server.go`](https://github.com/endurannsu/auth/blob/main/internal/app/server.go) (Server assembly), [`internal/adapter/in/http/handler.go`](https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/handler.go) (Auth handlers), [`internal/service/service.go`](https://github.com/endurannsu/auth/blob/main/internal/service/service.go) (Auth and sessions), [`internal/adapter/out/postgres/auth_service_repository.go`](https://github.com/endurannsu/auth/blob/main/internal/adapter/out/postgres/auth_service_repository.go) (PostgreSQL repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entry"]
  node_router["HTTP routes<br/>[router.go]"]
  node_handler["Auth handlers<br/>[handler.go]"]
  node_dto["Request responses<br/>[auth.go]"]
end

subgraph group_auth["Authentication"]
  node_auth_service["Auth and sessions<br/>[service.go]"]
  node_domain_models["Domain records<br/>[entity.go]"]
end

subgraph group_recovery["Password recovery"]
  node_recovery_service["OTP recovery<br/>[service.go]"]
end

subgraph group_persistence["Persistence and runtime"]
  node_repository_contracts["Repository contracts<br/>[repository.go]"]
  node_postgres_adapter["PostgreSQL repositories"]
  node_postgres[("PostgreSQL")]
  node_config["Service configuration<br/>[config.go]"]
  node_server["Server assembly<br/>[server.go]"]
  node_process["Service startup<br/>[main.go]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_router
node_router -->|"routes to"| node_handler
node_handler -->|"binds and returns"| node_dto
node_handler -->|"calls auth operations"| node_auth_service
node_handler -->|"calls reset operations"| node_recovery_service
node_auth_service -->|"uses interfaces"| node_repository_contracts
node_recovery_service -->|"uses interfaces"| node_repository_contracts
node_auth_service -->|"reads user records"| node_domain_models
node_recovery_service -->|"uses reset records"| node_domain_models
node_postgres_adapter -->|"implements"| node_repository_contracts
node_postgres_adapter -->|"queries"| node_postgres
node_process -->|"loads configuration"| node_config
node_process -->|"builds and starts"| node_server
node_server -->|"receives settings"| node_config
node_server -->|"constructs repositories"| node_postgres_adapter
node_server -->|"constructs service"| node_auth_service
node_server -->|"constructs handler"| node_handler
node_server -->|"constructs router"| node_router

click node_router "https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/router.go"
click node_handler "https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/handler.go"
click node_dto "https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/dto/auth.go"
click node_auth_service "https://github.com/endurannsu/auth/blob/main/internal/service/service.go"
click node_recovery_service "https://github.com/endurannsu/auth/blob/main/internal/service/service.go"
click node_domain_models "https://github.com/endurannsu/auth/blob/main/internal/domain/entity.go"
click node_repository_contracts "https://github.com/endurannsu/auth/blob/main/internal/domain/repository.go"
click node_postgres_adapter "https://github.com/endurannsu/auth/blob/main/internal/adapter/out/postgres/auth_service_repository.go"
click node_config "https://github.com/endurannsu/auth/blob/main/internal/app/config.go"
click node_server "https://github.com/endurannsu/auth/blob/main/internal/app/server.go"
click node_process "https://github.com/endurannsu/auth/blob/main/cmd/auth/main.go"

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_router,node_handler,node_dto,node_client toneBlue
class node_auth_service,node_domain_models toneAmber
class node_recovery_service toneMint
class node_repository_contracts,node_postgres_adapter,node_postgres,node_config,node_server,node_process toneRose
```

## Components

### HTTP entry

- [HTTP routes](https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/router.go): `internal/adapter/in/http/router.go`
- [Auth handlers](https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/handler.go): `internal/adapter/in/http/handler.go`
- [Request responses](https://github.com/endurannsu/auth/blob/main/internal/adapter/in/http/dto/auth.go): `internal/adapter/in/http/dto/auth.go`

### Authentication

- [Auth and sessions](https://github.com/endurannsu/auth/blob/main/internal/service/service.go): `internal/service/service.go`
- [Domain records](https://github.com/endurannsu/auth/blob/main/internal/domain/entity.go): `internal/domain/entity.go`

### Password recovery

- [OTP recovery](https://github.com/endurannsu/auth/blob/main/internal/service/service.go): `internal/service/service.go`

### Persistence and runtime

- [Repository contracts](https://github.com/endurannsu/auth/blob/main/internal/domain/repository.go): `internal/domain/repository.go`
- [PostgreSQL repositories](https://github.com/endurannsu/auth/blob/main/internal/adapter/out/postgres/auth_service_repository.go): `internal/adapter/out/postgres/auth_service_repository.go`
- **PostgreSQL**
- [Service configuration](https://github.com/endurannsu/auth/blob/main/internal/app/config.go): `internal/app/config.go`
- [Server assembly](https://github.com/endurannsu/auth/blob/main/internal/app/server.go): `internal/app/server.go`
- [Service startup](https://github.com/endurannsu/auth/blob/main/cmd/auth/main.go): `cmd/auth/main.go`

### Other components

- **API client**

## Connections

- API client → HTTP routes: sends requests (evidence: `internal/adapter/in/http/router.go`)
- HTTP routes → Auth handlers: routes to (evidence: `internal/adapter/in/http/router.go`)
- Auth handlers → Request responses: binds and returns (evidence: `internal/adapter/in/http/handler.go`)
- Auth handlers → Auth and sessions: calls auth operations (evidence: `internal/adapter/in/http/handler.go`)
- Auth handlers → OTP recovery: calls reset operations (evidence: `internal/adapter/in/http/handler.go`)
- Auth and sessions → Repository contracts: uses interfaces (evidence: `internal/service/service.go`)
- OTP recovery → Repository contracts: uses interfaces (evidence: `internal/service/service.go`)
- Auth and sessions → Domain records: reads user records (evidence: `internal/service/service.go`)
- OTP recovery → Domain records: uses reset records (evidence: `internal/service/service.go`)
- PostgreSQL repositories → Repository contracts: implements (evidence: `internal/adapter/out/postgres/auth_service_repository.go`)
- PostgreSQL repositories → PostgreSQL: queries (evidence: `internal/adapter/out/postgres/auth_service_repository.go`)
- Service startup → Service configuration: loads configuration (evidence: `cmd/auth/main.go`)
- Service startup → Server assembly: builds and starts (evidence: `cmd/auth/main.go`)
- Server assembly → Service configuration: receives settings (evidence: `internal/app/server.go`)
- Server assembly → PostgreSQL repositories: constructs repositories (evidence: `internal/app/server.go`)
- Server assembly → Auth and sessions: constructs service (evidence: `internal/app/server.go`)
- Server assembly → Auth handlers: constructs handler (evidence: `internal/app/server.go`)
- Server assembly → HTTP routes: constructs router (evidence: `internal/app/server.go`)
