# pereiraadiel/challenge-based-auth architecture

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

- Interactive diagram: https://gitdiagram.com/pereiraadiel/challenge-based-auth
- Repository: https://github.com/pereiraadiel/challenge-based-auth

## Overview

This is a web application for authentication using user-selected word, image, or number sets. Users register and receive a secret set, request a challenge, select groups containing their secret elements, and authenticate; authenticated users can view or change their set. The graph preserves the sampled client/server calls and domain stages. The README is empty, and unsampled routes and module bindings are represented only where the source index supports them; uncertain wiring is omitted.

Main entry points: [`client/src/app`](https://github.com/pereiraadiel/challenge-based-auth/tree/master/client/src/app) (Next.js pages), [`server/src/domain/services/authenticateUser.service.ts`](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/services/authenticateUser.service.ts) (Sign-in challenge), [`server/src/domain/services/users.service.ts`](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/services/users.service.ts) (User lifecycle), [`server/src/infra/providers/redis.provider.ts`](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/providers/redis.provider.ts) (Redis provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Next.js pages"]
  node_ui["UI components"]
  node_clientstate["Local session<br/>[useLocalStorage.ts]"]
  node_clientapi["HTTP API client<br/>[api.util.ts]"]
  node_contracts["User contracts<br/>[user.contract.ts]"]
end

subgraph group_server["API and domain"]
  node_authcontroller["Auth controller<br/>[auth.controller.ts]"]
  node_userscontroller["Users controller"]
  node_authservice["Sign-in challenge"]
  node_userservice["User lifecycle<br/>[users.service.ts]"]
  node_setlogic["Set generation<br/>[set.util.ts]"]
  node_usermapper["User mapping<br/>[users.mapper.ts]"]
  node_userentity["User entity<br/>[user.entity.ts]"]
  node_repocontracts["Repository contracts"]
  node_guard["Auth guard<br/>[auth.guard.ts]"]
  node_interceptor["Auth interceptor"]
  node_appmodule["App module<br/>[app.module.ts]"]
end

subgraph group_storage["Redis storage"]
  node_authrepo["Auth cache"]
  node_tokenrepo["Token cache"]
  node_usersrepo["User cache"]
  node_redisprovider["Redis provider<br/>[redis.provider.ts]"]
end

node_visitor(("Visitor"))
node_redis[("Redis")]

node_visitor -->|"uses"| node_web
node_web -->|"renders"| node_ui
node_web -->|"stores session"| node_clientstate
node_web -->|"requests"| node_clientapi
node_clientapi -.->|"calls auth"| node_authcontroller
node_clientapi -.->|"calls users"| node_userscontroller
node_authcontroller -->|"delegates"| node_authservice
node_userscontroller -->|"delegates"| node_userservice
node_authservice -->|"uses repositories"| node_repocontracts
node_userservice -->|"uses repositories"| node_repocontracts
node_authservice -->|"builds challenge"| node_setlogic
node_authservice -->|"maps secret set"| node_usermapper
node_userservice -->|"generates user set"| node_setlogic
node_userservice -->|"maps responses"| node_usermapper
node_usermapper -->|"maps entity"| node_userentity
node_authrepo -->|"reads and writes"| node_redisprovider
node_tokenrepo -->|"reads and writes"| node_redisprovider
node_usersrepo -->|"reads and writes"| node_redisprovider
node_redisprovider -->|"stores data"| node_redis
node_appmodule -->|"registers guard"| node_guard
node_userscontroller -->|"uses interceptor"| node_interceptor
node_appmodule -->|"imports"| node_interceptor

click node_web "https://github.com/pereiraadiel/challenge-based-auth/tree/master/client/src/app"
click node_ui "https://github.com/pereiraadiel/challenge-based-auth/tree/master/client/src/app/components"
click node_clientstate "https://github.com/pereiraadiel/challenge-based-auth/blob/master/client/src/hooks/useLocalStorage.ts"
click node_clientapi "https://github.com/pereiraadiel/challenge-based-auth/blob/master/client/src/utils/api.util.ts"
click node_contracts "https://github.com/pereiraadiel/challenge-based-auth/blob/master/client/src/app/contracts/user.contract.ts"
click node_authcontroller "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/controllers/auth.controller.ts"
click node_userscontroller "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/controllers/users.controller.ts"
click node_authservice "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/services/authenticateUser.service.ts"
click node_userservice "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/services/users.service.ts"
click node_setlogic "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/utils/set.util.ts"
click node_usermapper "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/mappers/users.mapper.ts"
click node_userentity "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/entities/user.entity.ts"
click node_repocontracts "https://github.com/pereiraadiel/challenge-based-auth/tree/master/server/src/domain/contracts/repositories"
click node_authrepo "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/repositories/auth.cache.repository.ts"
click node_tokenrepo "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/repositories/token.cache.repository.ts"
click node_usersrepo "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/repositories/users.cache.repository.ts"
click node_redisprovider "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/providers/redis.provider.ts"
click node_guard "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/guards/auth.guard.ts"
click node_interceptor "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/interceptors/auth.interceptor.ts"
click node_appmodule "https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/modules/app.module.ts"

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_web,node_ui,node_clientstate,node_clientapi,node_contracts toneBlue
class node_authcontroller,node_userscontroller,node_authservice,node_userservice,node_setlogic,node_usermapper,node_userentity,node_repocontracts,node_guard,node_interceptor,node_appmodule,node_redis toneAmber
class node_authrepo,node_tokenrepo,node_usersrepo,node_redisprovider toneMint
class node_visitor toneIndigo
```

## Components

### Web client

- [Next.js pages](https://github.com/pereiraadiel/challenge-based-auth/tree/master/client/src/app): `client/src/app`
- [UI components](https://github.com/pereiraadiel/challenge-based-auth/tree/master/client/src/app/components): `client/src/app/components`
- [Local session](https://github.com/pereiraadiel/challenge-based-auth/blob/master/client/src/hooks/useLocalStorage.ts): `client/src/hooks/useLocalStorage.ts`
- [HTTP API client](https://github.com/pereiraadiel/challenge-based-auth/blob/master/client/src/utils/api.util.ts): `client/src/utils/api.util.ts`
- [User contracts](https://github.com/pereiraadiel/challenge-based-auth/blob/master/client/src/app/contracts/user.contract.ts): `client/src/app/contracts/user.contract.ts`

### API and domain

- [Auth controller](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/controllers/auth.controller.ts): `server/src/infra/controllers/auth.controller.ts`
- [Users controller](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/controllers/users.controller.ts): `server/src/infra/controllers/users.controller.ts`
- [Sign-in challenge](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/services/authenticateUser.service.ts): `server/src/domain/services/authenticateUser.service.ts`
- [User lifecycle](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/services/users.service.ts): `server/src/domain/services/users.service.ts`
- [Set generation](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/utils/set.util.ts): `server/src/domain/utils/set.util.ts`
- [User mapping](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/mappers/users.mapper.ts): `server/src/domain/mappers/users.mapper.ts`
- [User entity](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/domain/entities/user.entity.ts): `server/src/domain/entities/user.entity.ts`
- [Repository contracts](https://github.com/pereiraadiel/challenge-based-auth/tree/master/server/src/domain/contracts/repositories): `server/src/domain/contracts/repositories`
- [Auth guard](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/guards/auth.guard.ts): `server/src/infra/guards/auth.guard.ts`
- [Auth interceptor](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/interceptors/auth.interceptor.ts): `server/src/infra/interceptors/auth.interceptor.ts`
- [App module](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/modules/app.module.ts): `server/src/infra/modules/app.module.ts`

### Redis storage

- [Auth cache](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/repositories/auth.cache.repository.ts): `server/src/infra/repositories/auth.cache.repository.ts`
- [Token cache](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/repositories/token.cache.repository.ts): `server/src/infra/repositories/token.cache.repository.ts`
- [User cache](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/repositories/users.cache.repository.ts): `server/src/infra/repositories/users.cache.repository.ts`
- [Redis provider](https://github.com/pereiraadiel/challenge-based-auth/blob/master/server/src/infra/providers/redis.provider.ts): `server/src/infra/providers/redis.provider.ts`

### Other components

- **Visitor**
- **Redis**

## Connections

- Visitor → Next.js pages: uses (evidence: `client/src/app/page.tsx`)
- Next.js pages → UI components: renders (evidence: `client/src/app/page.tsx`)
- Next.js pages → Local session: stores session (evidence: `client/src/app/page.tsx`)
- Next.js pages → HTTP API client: requests (evidence: `client/src/app/page.tsx`)
- HTTP API client → Auth controller: calls auth
- HTTP API client → Users controller: calls users
- Auth controller → Sign-in challenge: delegates (evidence: `server/src/infra/controllers/auth.controller.ts`)
- Users controller → User lifecycle: delegates (evidence: `server/src/infra/controllers/users.controller.ts`)
- Sign-in challenge → Repository contracts: uses repositories (evidence: `server/src/domain/services/authenticateUser.service.ts`)
- User lifecycle → Repository contracts: uses repositories (evidence: `server/src/domain/services/users.service.ts`)
- Sign-in challenge → Set generation: builds challenge (evidence: `server/src/domain/services/authenticateUser.service.ts`)
- Sign-in challenge → User mapping: maps secret set (evidence: `server/src/domain/services/authenticateUser.service.ts`)
- User lifecycle → Set generation: generates user set (evidence: `server/src/domain/services/users.service.ts`)
- User lifecycle → User mapping: maps responses (evidence: `server/src/domain/services/users.service.ts`)
- User mapping → User entity: maps entity (evidence: `server/src/domain/mappers/users.mapper.ts`)
- Auth cache → Redis provider: reads and writes (evidence: `server/src/infra/repositories/auth.cache.repository.ts`)
- Token cache → Redis provider: reads and writes (evidence: `server/src/infra/repositories/token.cache.repository.ts`)
- User cache → Redis provider: reads and writes (evidence: `server/src/infra/repositories/users.cache.repository.ts`)
- Redis provider → Redis: stores data (evidence: `server/src/infra/providers/redis.provider.ts`)
- App module → Auth guard: registers guard (evidence: `server/src/infra/modules/app.module.ts`)
- Users controller → Auth interceptor: uses interceptor (evidence: `server/src/infra/controllers/users.controller.ts`)
- App module → Auth interceptor: imports (evidence: `server/src/infra/modules/app.module.ts`)
