9. Estrutura e Arquitetura do Projeto

9.1. Arquitetura da Aplicação

A API Trace Point adota uma arquitetura em camadas (Layered Architecture), um padrão comum para aplicações backend robustas e manuteníveis. Esta abordagem promove a separação de responsabilidades, facilitando o desenvolvimento, testes e a evolução do sistema. As principais camadas são:

• Camada de Rotas (src/routes/):

  Responsável por definir os endpoints da API (URLs e métodos HTTP). Cada arquivo de rota agrupa os endpoints de um recurso específico (ex: UserRoutes.ts para usuários). As rotas recebem as requisições HTTP e as direcionam para os Controllers apropriados, aplicando middlewares de nível de rota quando necessário (ex: para autenticação específica).

• Camada de Controladores (src/controllers/):

  Atua como intermediária entre as rotas e os serviços. Os controllers extraem dados da requisição (parâmetros, corpo, queries), validam esses dados (frequentemente utilizando DTOs e class-validator), invocam os métodos da camada de Serviço para executar a lógica de negócios, e então formatam e enviam a resposta HTTP de volta ao cliente.

• Camada de Serviços (src/service/):

  Contém a lógica de negócios central da aplicação. Os serviços orquestram as operações, manipulam os dados, realizam cálculos complexos e interagem com a camada de Repositório para persistência de dados. Esta camada mantém os controllers "magros" e focados na interação HTTP.

• Camada de Repositórios (src/repositories/):

  Responsável pelo acesso e manipulação de dados no banco de dados. Utilizando o TypeORM, os repositórios abstraem as consultas SQL complexas, permitindo que a camada de Serviço interaja com o banco de forma mais orientada a objetos. Cada entidade geralmente possui seu próprio repositório.

• Modelos/Entidades (src/models/):

  Definem a estrutura dos dados da aplicação e como eles são mapeados para as tabelas do banco de dados. São classes TypeScript decoradas com anotações do TypeORM (@Entity, @Column, etc.) que representam as tabelas e seus relacionamentos.

• DTOs - Data Transfer Objects (src/DTO/):

  São objetos simples usados para transferir dados entre as camadas, especialmente entre o cliente e os controllers, e entre controllers e services. Ajudam a definir a "forma" dos dados esperados e retornados, e são frequentemente usados para validação de entrada.

• Middlewares (src/middleware/):

  Funções que têm acesso aos objetos de requisição (req), resposta (res) e à próxima função de middleware no ciclo de requisição-resposta da aplicação. São usados para tarefas como autenticação (JwtRequired.ts), autorização (RoleCheck.ts), tratamento de erros global (ErrorsHandler.ts), e validações específicas (ValidateId.ts).

• Utilitários (src/utils/):

  Módulos contendo funções e classes auxiliares reutilizáveis em várias partes da aplicação, como gerenciamento de tokens (TokenManager.ts), validadores customizados (ExistsValidator.ts, ValidateRequestBody.ts), etc.

• Configurações (src/config/ e src/db_config/):

  Arquivos para configurações da aplicação, como carregamento de variáveis de ambiente (EsportEnv.ts) e a configuração da conexão com o banco de dados (AppDataSource.ts).

Fluxo de uma Requisição (Exemplo Simplificado):

1. O cliente envia uma requisição HTTP para um endpoint da API.
2. O Express.js recebe a requisição e a encaminha para a Rota correspondente.
3. Middlewares de rota (ex: autenticação) são executados.
4. A Rota chama o método apropriado no Controller.
5. O Controller valida os dados de entrada (usando DTOs) e chama o Serviço.
6. O Serviço executa a lógica de negócios, possivelmente chamando um ou mais Repositórios.
7. O Repositório interage com o banco de dados (via TypeORM) para ler ou escrever dados.
8. Os dados (ou um status de sucesso/erro) retornam pela mesma cadeia: Repositório -> Serviço -> Controller.
9. O Controller formata a resposta e a envia de volta ao cliente.
10. Se ocorrer um erro em qualquer ponto, ele pode ser capturado e tratado pelo middleware de Erros global.

9.2. Estrutura de Pastas Detalhada

A organização de pastas e arquivos principais do projeto é a seguinte:

Trace_Point/
├── .env                       # Variáveis de ambiente (local, não versionado)
├── .env.copy                  # Arquivo de exemplo para .env
├── .dockerignore              # Especifica arquivos a serem ignorados pelo Docker
├── docker-compose.yml         # Define e orquestra os serviços Docker (app, banco, etc.)
├── Dockerfile                 # Instruções para construir a imagem Docker da aplicação
├── package.json               # Metadados do projeto, dependências e scripts NPM
├── tsconfig.json              # Configurações do compilador TypeScript
├── README.md                  # Documentação principal do projeto (Markdown)
└── src/                       # Código fonte da aplicação
    ├── index.ts               # Ponto de entrada principal da aplicação, inicia o servidor
    ├── server.ts              # Configuração do servidor Express e inicialização do AppDataSource
    │
    ├── config/
    │   └── EsportEnv.ts       # Carrega e exporta variáveis de ambiente da aplicação
    │
    ├── controllers/           # Camada de controle (lida com requisições HTTP e envia respostas)
    │   ├── AuthController.ts    # Controller para autenticação (login, refresh token)
    │   ├── EventController.ts   # Controller para gerenciar operações de Eventos
    │   ├── PlaceController.ts   # Controller para gerenciar operações de Locais
    │   ├── UserController.ts    # Controller para gerenciar operações de Usuários
    │   └── VisitedController.ts # Controller para gerenciar operações de Visitas a Locais
    │
    ├── DTO/                   # Data Transfer Objects (definem a estrutura dos dados de entrada/saída da API)
    │   ├── wrappersDTO/       # DTOs para estruturas de dados aninhadas ou específicas
    │   │   ├── AddressDTO.ts  # DTO para dados de endereço
    │   │   └── LoginInfoDTO.ts# DTO para dados de login (email, senha)
    │   ├── BookingDTO.ts      # DTO para agendamento de usuário em evento
    │   ├── EventDTO.ts        # DTO para criação/atualização de Eventos
    │   ├── PlaceDTO.ts        # DTO para criação/atualização de Locais
    │   ├── UserDTO.ts         # DTO para criação/atualização de Usuários
    │   └── VisitedDTO.ts      # DTO para registro/atualização de Visitas
    │
    ├── error/                 # Classes e manipuladores de erro customizados
    │   ├── ErrorsHandler.ts   # Middleware global para tratamento de erros
    │   └── HttpException.ts   # Classe base para exceções HTTP customizadas
    │
    ├── middleware/            # Middlewares Express para diversas funcionalidades
    │   ├── ErrorsHandler.ts   # (Arquivo do middleware de erro)
    │   ├── JwtRequired.ts     # Middleware para exigir autenticação JWT
    │   ├── RoleCheck.ts       # Middleware para verificação de papéis de usuário
    │   └── ValidateId.ts      # Middleware para validar formato de IDs
    │
    ├── migrations/            # Arquivos de migração de banco de dados (TypeORM)
    │
    ├── models/                # Entidades do banco de dados (TypeORM) e Enums
    │   ├── enum/              # Enumerações
    │   │   ├── PlaceType.ts   # Enum para os tipos de Local
    │   │   └── UserRole.ts    # Enum para os papéis de Usuário
    │   ├── wrappers/          # Classes embutidas para modelos
    │   │   ├── Address.ts     # Classe/entidade embutida para Endereço
    │   │   └── LoginInfo.ts   # Classe/entidade embutida para Informações de Login
    │   ├── Event.ts           # Entidade Evento
    │   ├── Place.ts           # Entidade Local
    │   ├── User.ts            # Entidade Usuário
    │   └── VisitedPlaces.ts   # Entidade para Locais Visitados
    │
    ├── repositories/          # Camada de acesso a dados (TypeORM Repositories)
    │   ├── EventRepository.ts   # Exemplo: Repositório para Evento
    │   ├── PlaceRepository.ts   # Exemplo: Repositório para Local
    │   ├── UserRepository.ts    # Exemplo: Repositório para Usuário
    │   └── VisitedRepository.ts # Exemplo: Repositório para Visitas
    │
    ├── routes/                # Definição das rotas da API
    │   ├── AuthRoutes.ts      # Rotas de autenticação
    │   ├── EventRoutes.ts     # Rotas de Eventos
    │   ├── PlaceRoutes.ts     # Rotas de Locais
    │   ├── UserRoutes.ts      # Rotas de Usuários
    │   └── VisitedRoutes.ts   # Rotas de Visitas
    │
    ├── service/               # Camada de serviço (lógica de negócios)
    │   ├── AuthService.ts     # Serviço de autenticação
    │   ├── EventService.ts    # Serviço de Eventos
    │   ├── PlaceService.ts    # Serviço de Locais
    │   ├── UserService.ts     # Serviço de Usuários
    │   └── VisitedService.ts  # Serviço de Visitas
    │
    ├── utils/                 # Funções e classes utilitárias
    │   ├── ExistsValidator.ts # Validador de existência
    │   ├── TokenManager.ts    # Gerenciador de tokens JWT
    │   └── ValidateRequestBody.ts # Validador de corpo de requisição
    │
    ├── db_config/
    │   └── AppDataSource.ts   # Configuração da fonte de dados TypeORM
    │
    └── @types/                # Arquivos de definição de tipos TypeScript
        └── express/
            └── index.d.ts     # Extensões de tipo para o Express (ex: req.user)

Para uma exploração mais detalhada dos arquivos, navegue pelo repositório no GitHub.

Voltar para Visão Geral Referência da API Modelo Relacional (DER)