# devfullcycle/spec-pullrequest-ia architecture

> Architecture diagram of the GitHub repository devfullcycle/spec-pullrequest-ia, 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/devfullcycle/spec-pullrequest-ia
- Repository: https://github.com/devfullcycle/spec-pullrequest-ia

## Overview

O repositório documenta um gerenciador de arquivos na nuvem como aplicação-exemplo; seu foco declarado, porém, é o processo de desenvolvimento com agentes. O mapa abaixo cobre os runtimes presentes: autenticação por e-mail, navegação de itens e capacidades de upload/download representadas no código. A API é NestJS e o frontend Next.js, com PostgreSQL e storage de objetos. Algumas relações vêm de trechos e do índice de fontes; subsistemas não amostrados aparecem sem ligações específicas quando estas não podem ser confirmadas.

Main entry points: [`apps/web/lib/api/client.ts`](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/lib/api/client.ts) (Cliente da API), [`apps/api/src/app.module.ts`](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/app.module.ts) (Composição da API), [`apps/api/src/modules/auth/auth.controller.ts`](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/auth.controller.ts) (Rotas de autenticação), [`apps/api/src/modules/auth/sessions.service.ts`](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/sessions.service.ts) (Sessões e tokens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Frontend Next.js"]
  node_auth_ui["Telas de acesso<br/>[page.tsx]"]
  node_drive_ui["Drive e pastas<br/>[page.tsx]"]
  node_web_upload["Cliente de uploads<br/>[engine.ts]"]
  node_api_client["Cliente da API<br/>[client.ts]"]
end

subgraph group_auth["Autenticação"]
  node_auth_controller["Rotas de autenticação<br/>[auth.controller.ts]"]
  node_registration["Cadastro e verificação"]
  node_sessions["Sessões e tokens"]
  node_auth_guard["Guarda de acesso<br/>[auth.guard.ts]"]
  node_users["Usuários<br/>[users.service.ts]"]
end

subgraph group_drive["Arquivos e uploads"]
  node_items_controller["Rotas de itens"]
  node_items_service["Regras de itens<br/>[items.service.ts]"]
  node_folders_controller["Rotas de pastas"]
  node_items_repository[("Persistência de itens")]
  node_uploads_controller["Rotas de upload"]
  node_uploads_service["Serviço de uploads<br/>[uploads.service.ts]"]
  node_quota["Cotas<br/>[quota.service.ts]"]
end

subgraph group_platform["Serviços da API"]
  node_storage_port["Contrato de storage<br/>[file-storage.ts]"]
  node_gcs["Cloud Storage"]
  node_database[("PostgreSQL<br/>[prisma.service.ts]")]
  node_mail["Envio de e-mail<br/>[mail-sender.ts]"]
  node_app_module["Composição da API<br/>[app.module.ts]"]
end

node_person(("Pessoa usuária"))

node_person -->|"inicia sessão"| node_auth_ui
node_person -->|"usa o drive"| node_drive_ui
node_auth_ui -.->|"solicita acesso"| node_api_client
node_drive_ui -.->|"solicita itens"| node_api_client
node_web_upload -.->|"usa API"| node_api_client
node_api_client -.->|"chama API"| node_auth_controller
node_api_client -.->|"chama API"| node_items_controller
node_api_client -.->|"chama API"| node_uploads_controller
node_auth_controller -->|"delegates to"| node_registration
node_auth_controller -->|"delegates to"| node_sessions
node_auth_controller -.->|"delegates to"| node_mail
node_sessions -->|"loads user"| node_users
node_sessions -->|"issues tokens"| node_auth_guard
node_auth_guard -->|"verifies access token"| node_sessions
node_items_controller -->|"guards routes"| node_auth_guard
node_items_controller -->|"delegates to"| node_items_service
node_folders_controller -->|"delegates to"| node_items_service
node_items_service -->|"queries"| node_items_repository
node_items_service -->|"requests signed URL"| node_storage_port
node_uploads_controller -->|"guards routes"| node_auth_guard
node_uploads_controller -->|"delegates to"| node_uploads_service
node_uploads_service -.->|"uses storage"| node_storage_port
node_uploads_service -.->|"checks quota"| node_quota
node_storage_port -->|"implemented by"| node_gcs
node_app_module -->|"registers module"| node_auth_controller
node_app_module -->|"registers module"| node_items_controller
node_app_module -->|"registers module"| node_uploads_controller
node_app_module -->|"registers module"| node_database
node_app_module -->|"registers module"| node_mail

click node_auth_ui "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/app/(auth)/entrar/page.tsx"
click node_drive_ui "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/app/(drive)/page.tsx"
click node_web_upload "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/lib/uploads/engine.ts"
click node_api_client "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/lib/api/client.ts"
click node_auth_controller "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_registration "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/registration.service.ts"
click node_sessions "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/sessions.service.ts"
click node_auth_guard "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/common/auth/auth.guard.ts"
click node_users "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/users/users.service.ts"
click node_items_controller "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/items.controller.ts"
click node_items_service "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/items.service.ts"
click node_folders_controller "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/folders.controller.ts"
click node_items_repository "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/items.repository.ts"
click node_uploads_controller "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/uploads/uploads.controller.ts"
click node_uploads_service "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/uploads/uploads.service.ts"
click node_quota "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/quota/quota.service.ts"
click node_storage_port "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/storage/file-storage.ts"
click node_gcs "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/storage/gcs-file-storage.ts"
click node_database "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/database/prisma.service.ts"
click node_mail "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/mail/mail-sender.ts"
click node_app_module "https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/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_auth_ui,node_drive_ui,node_web_upload,node_api_client toneBlue
class node_auth_controller,node_registration,node_sessions,node_auth_guard,node_users toneAmber
class node_items_controller,node_items_service,node_folders_controller,node_items_repository,node_uploads_controller,node_uploads_service,node_quota toneMint
class node_storage_port,node_gcs,node_database,node_mail,node_app_module toneRose
class node_person toneIndigo
```

## Components

### Frontend Next.js

- [Telas de acesso](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/app/(auth)/entrar/page.tsx): `apps/web/app/(auth)/entrar/page.tsx`
- [Drive e pastas](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/app/(drive)/page.tsx): `apps/web/app/(drive)/page.tsx`
- [Cliente de uploads](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/lib/uploads/engine.ts): `apps/web/lib/uploads/engine.ts`
- [Cliente da API](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/web/lib/api/client.ts): `apps/web/lib/api/client.ts`

### Autenticação

- [Rotas de autenticação](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Cadastro e verificação](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/registration.service.ts): `apps/api/src/modules/auth/registration.service.ts`
- [Sessões e tokens](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/auth/sessions.service.ts): `apps/api/src/modules/auth/sessions.service.ts`
- [Guarda de acesso](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/common/auth/auth.guard.ts): `apps/api/src/common/auth/auth.guard.ts`
- [Usuários](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/users/users.service.ts): `apps/api/src/modules/users/users.service.ts`

### Arquivos e uploads

- [Rotas de itens](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/items.controller.ts): `apps/api/src/modules/items/items.controller.ts`
- [Regras de itens](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/items.service.ts): `apps/api/src/modules/items/items.service.ts`
- [Rotas de pastas](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/folders.controller.ts): `apps/api/src/modules/items/folders.controller.ts`
- [Persistência de itens](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/items/items.repository.ts): `apps/api/src/modules/items/items.repository.ts`
- [Rotas de upload](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/uploads/uploads.controller.ts): `apps/api/src/modules/uploads/uploads.controller.ts`
- [Serviço de uploads](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/uploads/uploads.service.ts): `apps/api/src/modules/uploads/uploads.service.ts`
- [Cotas](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/modules/quota/quota.service.ts): `apps/api/src/modules/quota/quota.service.ts`

### Serviços da API

- [Contrato de storage](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/storage/file-storage.ts): `apps/api/src/infra/storage/file-storage.ts`
- [Cloud Storage](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/storage/gcs-file-storage.ts): `apps/api/src/infra/storage/gcs-file-storage.ts`
- [PostgreSQL](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/database/prisma.service.ts): `apps/api/src/infra/database/prisma.service.ts`
- [Envio de e-mail](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/infra/mail/mail-sender.ts): `apps/api/src/infra/mail/mail-sender.ts`
- [Composição da API](https://github.com/devfullcycle/spec-pullrequest-ia/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`

### Other components

- **Pessoa usuária**

## Connections

- Pessoa usuária → Telas de acesso: inicia sessão (evidence: `README.md`)
- Pessoa usuária → Drive e pastas: usa o drive (evidence: `README.md`)
- Telas de acesso → Cliente da API: solicita acesso
- Drive e pastas → Cliente da API: solicita itens
- Cliente de uploads → Cliente da API: usa API
- Cliente da API → Rotas de autenticação: chama API (evidence: `README.md`)
- Cliente da API → Rotas de itens: chama API (evidence: `README.md`)
- Cliente da API → Rotas de upload: chama API (evidence: `README.md`)
- Rotas de autenticação → Cadastro e verificação: delegates to (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Rotas de autenticação → Sessões e tokens: delegates to (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Rotas de autenticação → Envio de e-mail: delegates to
- Sessões e tokens → Usuários: loads user (evidence: `apps/api/src/modules/auth/sessions.service.ts`)
- Sessões e tokens → Guarda de acesso: issues tokens (evidence: `apps/api/src/modules/auth/sessions.service.ts`)
- Guarda de acesso → Sessões e tokens: verifies access token (evidence: `apps/api/src/common/auth/auth.guard.ts`)
- Rotas de itens → Guarda de acesso: guards routes (evidence: `apps/api/src/modules/items/items.controller.ts`)
- Rotas de itens → Regras de itens: delegates to (evidence: `apps/api/src/modules/items/items.controller.ts`)
- Rotas de pastas → Regras de itens: delegates to (evidence: `apps/api/src/modules/items/folders.controller.ts`)
- Regras de itens → Persistência de itens: queries (evidence: `apps/api/src/modules/items/items.service.ts`)
- Regras de itens → Contrato de storage: requests signed URL (evidence: `apps/api/src/modules/items/items.service.ts`)
- Rotas de upload → Guarda de acesso: guards routes (evidence: `apps/api/src/modules/uploads/uploads.controller.ts`)
- Rotas de upload → Serviço de uploads: delegates to (evidence: `apps/api/src/modules/uploads/uploads.controller.ts`)
- Serviço de uploads → Contrato de storage: uses storage
- Serviço de uploads → Cotas: checks quota
- Contrato de storage → Cloud Storage: implemented by (evidence: `apps/api/src/infra/storage/gcs-file-storage.ts`)
- Composição da API → Rotas de autenticação: registers module (evidence: `apps/api/src/app.module.ts`)
- Composição da API → Rotas de itens: registers module (evidence: `apps/api/src/app.module.ts`)
- Composição da API → Rotas de upload: registers module (evidence: `apps/api/src/app.module.ts`)
- Composição da API → PostgreSQL: registers module (evidence: `apps/api/src/app.module.ts`)
- Composição da API → Envio de e-mail: registers module (evidence: `apps/api/src/app.module.ts`)