# silascunha97/api_para_treinos architecture

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

- Interactive diagram: https://gitdiagram.com/silascunha97/api_para_treinos
- Repository: https://github.com/silascunha97/api_para_treinos

## Overview

#### Purpose and Entry Points
Workout Tracker is a TypeScript backend for recording people, exercise catalog entries, workout sessions, and performed sets, with JWT-based account access. Runtime bootstrapping is through `src/index.ts`, which assembles the Express/Apollo application from `src/main/app.ts`; the GraphQL server is defined in `src/presentation/graphql/server.ts` and exposed at `/graphql`.

#### Architectural Shape
The repository follows dependency inversion across four layers:
- **Domain:** entities, DTOs, and contracts independent of frameworks: `src/domain/entities/`, `src/domain/repositories/`, `src/domain/providers/`.
- **Application:** operation-specific orchestration through use cases: `src/application/use-cases/auth/`, `src/application/use-cases/exercicio/`.
- **Infrastructure:** Prisma persistence plus replaceable service adapters: `src/infrastructure/repositories/`, `src/infrastructure/providers/`.
- **Presentation/composition:** GraphQL schema and resolvers invoke factory-built use cases: `src/presentation/graphql/`, `src/main/factories/`.

#### Workout Domain and Flows
The core model is `Pessoa → SessaoTreino → Serie`, with each series linked to an `Exercicio`. Domain representations are in `src/domain/entities/Pessoa.ts`, `src/domain/entities/SessaoTreino.ts`, and `src/domain/entities/Serie.ts`; API contracts are carried by `src/domain/dtos/`.

A typical mutation/query flow is GraphQL resolver → factory-composed use case → domain repository interface → Prisma/cached repository → PostgreSQL. Current operations include person creation, exercise creation/listing, and session completion, centered in `src/application/use-cases/pessoa/CriarPessoaUseCase.ts`, `src/application/use-cases/exercicio/CriarExercicioUseCase.ts`, and `src/application/use-cases/exercicio/FinalizarSessaoTreinoUseCase.ts`.

#### Authentication Boundary
Authentication is isolated behind provider and repository interfaces, preventing use cases from importing bcrypt, JWT, or Prisma. Account registration and password login are implemented in `src/application/use-cases/auth/CriarContaUseCase.ts` and `src/application/use-cases/auth/AutenticarComSenhaUseCase.ts`.

Concrete boundaries are bcrypt/JWT adapters (`src/infrastructure/providers/BcryptAdapter.ts`, `src/infrastructure/providers/JwtAdapter.ts`) and persisted user/refresh-token repositories (`src/infrastructure/repositories/PrismaUsuarioRepository.ts`, `src/infrastructure/repositories/PrismaRefreshTokenRepository.ts`). GraphQL context extracts Bearer credentials and guards protected operations through `src/presentation/graphql/context/index.ts` and `src/presentation/graphql/guards/graph.guards.ts`. Refresh-token rotation is stateful in PostgreSQL; access-token validation is stateless JWT.

#### GraphQL Presentation and Composition
Schema definitions and resolver registration are concentrated under `src/presentation/graphql/typeDefs/index.ts` and `src/presentation/graphql/resolvers/index.ts`, with feature resolvers such as `src/presentation/graphql/resolvers/authResolvers.ts`. Resolvers remain an adapter layer: dependencies are wired in focused composition roots, including `src/main/factories/authFactory.ts` and `src/main/factories/exercicioFactory.ts`. Presentation errors are normalized by `src/presentation/errors/formatError.ts`.

#### Persistence, Caching, and Async Metrics
PostgreSQL is the system of record, modeled in `prisma/schema.prisma` and accessed through the Prisma client at `src/infrastructure/database/prisma/prismaClient.ts`. Prisma repositories implement domain contracts; cache-decorated exercise/session repositories introduce Redis as an optional read boundary: `src/infrastructure/repositories/CachedExercicioRepository.ts`, `src/infrastructure/repositories/CachedSessaoTreinoRepository.ts`, and `src/infrastructure/providers/RedisAdapter.ts`.

Workout metric work is separated asynchronously through RabbitMQ (`src/infrastructure/providers/RabbitMQAdapter.ts`) and a consumer worker, `src/infrastructure/workers/treinoMetricsWorker.ts`, avoiding metric processing on the synchronous GraphQL request path.

#### Runtime and Infrastructure
The material runtime is Node.js 20+ with TypeScript, Express, and Apollo Server; PostgreSQL 16, Redis, and RabbitMQ are the external state/messaging services implied by adapters. Local/container deployment boundaries are captured in `Dockerfile` and `docker-compose.yml`; Prisma configuration is in `prisma.config.ts`. Environment typing and secrets/configuration contracts begin at `src/@types/environment.d.ts` and `.env.example`.

Main entry points: [`src/application/use-cases/exercicio/FinalizarSessaoTreinoUseCase.ts`](https://github.com/silascunha97/api_para_treinos/blob/main/src/application/use-cases/exercicio/FinalizarSessaoTreinoUseCase.ts) (Workout use cases), [`src/presentation/graphql/server.ts`](https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/server.ts) (GraphQL server), [`src/main/factories/authFactory.ts`](https://github.com/silascunha97/api_para_treinos/blob/main/src/main/factories/authFactory.ts) (Use-case factories), [`src/infrastructure/repositories/CachedExercicioRepository.ts`](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/repositories/CachedExercicioRepository.ts) (Cached workout repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_bootstrap["Node bootstrap<br/>entry point<br/>[index.ts]"]
  node_app["Express/Apollo app<br/>application assembly<br/>[app.ts]"]
end

subgraph group_presentation["Presentation &amp; Composition"]
  node_graphql_server["GraphQL server<br/>Apollo endpoint<br/>[server.ts]"]
  node_schema_resolvers["Schema &amp; resolvers<br/>GraphQL adapter<br/>[index.ts]"]
  node_graphql_context_guards["Auth context &amp; guards<br/>GraphQL authorization<br/>[index.ts]"]
  node_factories["Use-case factories<br/>composition roots<br/>[authFactory.ts]"]
end

subgraph group_application["Application"]
  node_workout_use_cases["Workout use cases<br/>application orchestration"]
  node_auth_use_cases["Auth use cases<br/>application orchestration"]
end

subgraph group_domain["Domain"]
  node_workout_model["Workout model<br/>domain entities<br/>[SessaoTreino.ts]"]
  node_domain_contracts{{"Repository &amp; provider contracts<br/>dependency-inversion boundary"}}
end

subgraph group_infrastructure["Infrastructure"]
  node_prisma_repositories["Prisma repositories<br/>persistence adapters"]
  node_cached_repositories["Cached workout repositories<br/>cache-decorated repositories"]
  node_auth_adapters["Bcrypt &amp; JWT adapters<br/>security adapters<br/>[JwtAdapter.ts]"]
  node_prisma_client["Prisma client<br/>database client<br/>[prismaClient.ts]"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[schema.prisma]")]
  node_redis[("Redis<br/>cache service<br/>[RedisAdapter.ts]")]
  node_rabbitmq["RabbitMQ<br/>message broker<br/>[RabbitMQAdapter.ts]"]
  node_metrics_worker["Training metrics worker<br/>async consumer"]
end

node_bootstrap -->|"starts"| node_app
node_app -->|"mounts"| node_graphql_server
node_graphql_server -->|"serves"| node_schema_resolvers
node_graphql_server -->|"builds context"| node_graphql_context_guards
node_schema_resolvers -->|"obtains use cases"| node_factories
node_factories -->|"wires"| node_workout_use_cases
node_factories -->|"wires"| node_auth_use_cases
node_graphql_context_guards -->|"validates access JWT"| node_auth_adapters
node_workout_use_cases -->|"orchestrates"| node_workout_model
node_workout_use_cases -->|"depends on"| node_domain_contracts
node_auth_use_cases -->|"depends on"| node_domain_contracts
node_domain_contracts -->|"implemented by"| node_prisma_repositories
node_domain_contracts -->|"implemented by"| node_cached_repositories
node_domain_contracts -->|"implemented by"| node_auth_adapters
node_prisma_repositories -->|"uses"| node_prisma_client
node_cached_repositories -->|"reads/writes cache"| node_redis
node_cached_repositories -.->|"falls through to"| node_prisma_repositories
node_prisma_client -->|"persists"| node_postgres
node_workout_use_cases -.->|"publishes metric work"| node_rabbitmq
node_rabbitmq -->|"delivers jobs"| node_metrics_worker

click node_bootstrap "https://github.com/silascunha97/api_para_treinos/blob/main/src/index.ts"
click node_app "https://github.com/silascunha97/api_para_treinos/blob/main/src/main/app.ts"
click node_graphql_server "https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/server.ts"
click node_schema_resolvers "https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/resolvers/index.ts"
click node_graphql_context_guards "https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/context/index.ts"
click node_factories "https://github.com/silascunha97/api_para_treinos/blob/main/src/main/factories/authFactory.ts"
click node_workout_use_cases "https://github.com/silascunha97/api_para_treinos/blob/main/src/application/use-cases/exercicio/FinalizarSessaoTreinoUseCase.ts"
click node_auth_use_cases "https://github.com/silascunha97/api_para_treinos/blob/main/src/application/use-cases/auth/AutenticarComSenhaUseCase.ts"
click node_workout_model "https://github.com/silascunha97/api_para_treinos/blob/main/src/domain/entities/SessaoTreino.ts"
click node_prisma_repositories "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/repositories/PrismaUsuarioRepository.ts"
click node_cached_repositories "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/repositories/CachedExercicioRepository.ts"
click node_auth_adapters "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/providers/JwtAdapter.ts"
click node_prisma_client "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/database/prisma/prismaClient.ts"
click node_postgres "https://github.com/silascunha97/api_para_treinos/blob/main/prisma/schema.prisma"
click node_redis "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/providers/RedisAdapter.ts"
click node_rabbitmq "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/providers/RabbitMQAdapter.ts"
click node_metrics_worker "https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/workers/treinoMetricsWorker.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_bootstrap,node_app toneBlue
class node_graphql_server,node_schema_resolvers,node_graphql_context_guards,node_factories toneAmber
class node_workout_use_cases,node_auth_use_cases toneMint
class node_workout_model,node_domain_contracts toneRose
class node_prisma_repositories,node_cached_repositories,node_auth_adapters,node_prisma_client,node_postgres,node_redis,node_rabbitmq,node_metrics_worker toneIndigo
```

## Components

### Runtime

- [Node bootstrap](https://github.com/silascunha97/api_para_treinos/blob/main/src/index.ts): entry point · `src/index.ts`
- [Express/Apollo app](https://github.com/silascunha97/api_para_treinos/blob/main/src/main/app.ts): application assembly · `src/main/app.ts`

### Presentation & Composition

- [GraphQL server](https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/server.ts): Apollo endpoint · Exposes the API at /graphql. · `src/presentation/graphql/server.ts`
- [Schema & resolvers](https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/resolvers/index.ts): GraphQL adapter · `src/presentation/graphql/resolvers/index.ts`
- [Auth context & guards](https://github.com/silascunha97/api_para_treinos/blob/main/src/presentation/graphql/context/index.ts): GraphQL authorization · `src/presentation/graphql/context/index.ts`
- [Use-case factories](https://github.com/silascunha97/api_para_treinos/blob/main/src/main/factories/authFactory.ts): composition roots · `src/main/factories/authFactory.ts`

### Application

- [Workout use cases](https://github.com/silascunha97/api_para_treinos/blob/main/src/application/use-cases/exercicio/FinalizarSessaoTreinoUseCase.ts): application orchestration · Creates people and exercises and completes workout sessions. · `src/application/use-cases/exercicio/FinalizarSessaoTreinoUseCase.ts`
- [Auth use cases](https://github.com/silascunha97/api_para_treinos/blob/main/src/application/use-cases/auth/AutenticarComSenhaUseCase.ts): application orchestration · Registers accounts and authenticates password login. · `src/application/use-cases/auth/AutenticarComSenhaUseCase.ts`

### Domain

- [Workout model](https://github.com/silascunha97/api_para_treinos/blob/main/src/domain/entities/SessaoTreino.ts): domain entities · Pessoa owns sessions; sessions contain series linked to exercises. · `src/domain/entities/SessaoTreino.ts`
- **Repository & provider contracts**: dependency-inversion boundary

### Infrastructure

- [Prisma repositories](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/repositories/PrismaUsuarioRepository.ts): persistence adapters · `src/infrastructure/repositories/PrismaUsuarioRepository.ts`
- [Cached workout repositories](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/repositories/CachedExercicioRepository.ts): cache-decorated repositories · Adds optional Redis reads for exercises and sessions. · `src/infrastructure/repositories/CachedExercicioRepository.ts`
- [Bcrypt & JWT adapters](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/providers/JwtAdapter.ts): security adapters · `src/infrastructure/providers/JwtAdapter.ts`
- [Prisma client](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/database/prisma/prismaClient.ts): database client · `src/infrastructure/database/prisma/prismaClient.ts`
- [PostgreSQL](https://github.com/silascunha97/api_para_treinos/blob/main/prisma/schema.prisma): system of record · Stores workout data, users, and refresh-token rotation state. · `prisma/schema.prisma`
- [Redis](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/providers/RedisAdapter.ts): cache service · `src/infrastructure/providers/RedisAdapter.ts`
- [RabbitMQ](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/providers/RabbitMQAdapter.ts): message broker · `src/infrastructure/providers/RabbitMQAdapter.ts`
- [Training metrics worker](https://github.com/silascunha97/api_para_treinos/blob/main/src/infrastructure/workers/treinoMetricsWorker.ts): async consumer · Processes workout metrics off the request path. · `src/infrastructure/workers/treinoMetricsWorker.ts`

## Connections

- Node bootstrap → Express/Apollo app: starts
- Express/Apollo app → GraphQL server: mounts
- GraphQL server → Schema & resolvers: serves
- GraphQL server → Auth context & guards: builds context
- Schema & resolvers → Use-case factories: obtains use cases
- Use-case factories → Workout use cases: wires
- Use-case factories → Auth use cases: wires
- Auth context & guards → Bcrypt & JWT adapters: validates access JWT
- Workout use cases → Workout model: orchestrates
- Workout use cases → Repository & provider contracts: depends on
- Auth use cases → Repository & provider contracts: depends on
- Repository & provider contracts → Prisma repositories: implemented by
- Repository & provider contracts → Cached workout repositories: implemented by
- Repository & provider contracts → Bcrypt & JWT adapters: implemented by
- Prisma repositories → Prisma client: uses
- Cached workout repositories → Redis: reads/writes cache
- Cached workout repositories → Prisma repositories: falls through to
- Prisma client → PostgreSQL: persists
- Workout use cases → RabbitMQ: publishes metric work
- RabbitMQ → Training metrics worker: delivers jobs