# unilopers/concessionaria architecture

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

- Interactive diagram: https://gitdiagram.com/unilopers/concessionaria
- Repository: https://github.com/unilopers/concessionaria

## Overview

1. **Overall shape**  
This repository is a single Spring Boot mini-ERP for a concessionária, organized as a layered monolith: REST controllers at the edge, service classes for business rules, Spring Data JPA repositories for persistence, and JPA entities as the domain model.

2. **API layer / entry points**  
The main HTTP surface is under `com.grupo8.concessionaria.controller`. It exposes resource-oriented endpoints for:
- clientes
- funcionários
- modelos
- veículos em estoque
- vendas and itens de venda
- ordens de serviço and itens de ordem de serviço
- movimentações financeiras  
There is also a `PublicController`, which represents the unauthenticated/public part of the API.

3. **Security boundary**  
Authentication is implemented with an API key, not session or OAuth. `ApiKeyAuthInterceptor`, `ApiKeyConfig`, and `WebConfig` form the request-filtering boundary: protected business routes require the `x-api-key` header, while `/public/**` and `/h2-console/**` remain open. Error handling for missing/invalid keys is standardized through `ApiErrorResponse`.

4. **Business/service layer**  
Each domain area has a service class in `model/service`, such as `ClienteService`, `VendaService`, `OrdemServicoService`, and `MovimentacaoFinanceiraService`. These services are the main place where business rules and cross-entity coordination live, sitting between controllers and repositories.

5. **Persistence layer**  
Persistence is handled by Spring Data JPA repositories in `model/repository`. Each major entity has its own repository, enabling CRUD-style database access with minimal boilerplate. The application uses an in-memory H2 database for development and local execution.

6. **Domain model**  
The core entities are:
- `Cliente`
- `Funcionario`
- `Modelo`
- `VeiculoEstoque`
- `Venda`
- `ItemVenda`
- `OrdemServico`
- `ItemOrdemServico`
- `Servico`
- `MovimentacaoFinanceira`  
There are also enums for status and classification, such as `StatusVeiculo`, `StatusOS`, `TipoPagamento`, `TipoMovimentacao`, and `OrigemMovimentacao`, which define the business state space.

7. **Typical data flow**  
A request usually follows: controller receives JSON → service validates/coordinates → repository persists or fetches entities → response is returned to the client. For richer workflows like sales or service orders, the service layer is where multiple tables/entities are likely updated together, including line items and financial records.

8. **Async subsystem**  
There is a small asynchronous branch under `async`, with `AsyncConfig`, `ClienteAsyncService`, and `VendaAsyncService`. This suggests some operations are intended to run off the request thread, likely for background processing or non-blocking domain work related to customer and sales flows.

9. **Configuration and runtime**  
`application.properties` centralizes runtime settings, including the API key value and H2 configuration. The app is started from `ConcessionariaApplication`, and the project is built with Maven Wrapper, making the runtime stack Java + Spring Boot + Spring Data JPA + H2.

10. **Testing and validation**  
The test suite includes `ApiKeyIntegrationTest`, which validates the security boundary: blocked access without/with wrong key and allowed access with the correct key, plus public-route access. There is also a `load-tests/ClienteDavi.py` script, indicating manual or scripted load testing for at least the client-related API.

11. **Architecture summary for a diagram**  
If drawing this system, show one HTTP API boundary guarded by API-key middleware/interceptor, a service layer beneath it, JPA repositories connected to an H2 database, and a separate asynchronous execution path for selected operations. The main domain centers on dealership entities, sales, service orders, inventory, and finance.

Main entry points: [`src/main/java/com/grupo8/concessionaria/config/ApiKeyAuthInterceptor.java`](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiKeyAuthInterceptor.java) (API key check), [`src/main/java/com/grupo8/concessionaria/config/WebConfig.java`](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/WebConfig.java) (Web config), [`src/main/java/com/grupo8/concessionaria/model/service/ClienteService.java`](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/ClienteService.java) (Cliente svc), [`src/main/java/com/grupo8/concessionaria/model/service/VendaService.java`](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/VendaService.java) (Venda svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app(("App<br/>Spring Boot entrypoint"))
end

subgraph group_api["API"]
  node_webconfig["Web config<br/>MVC config<br/>[WebConfig.java]"]
  node_apikeyconfig["API key cfg<br/>security config<br/>[ApiKeyConfig.java]"]
  node_apikeyinterceptor["API key check<br/>request interceptor"]
  node_apierror["API error<br/>error payload"]
  node_publicctl["Public API<br/>public controller"]
  node_clientectl["Clientes<br/>REST controller"]
  node_vendactl["Vendas<br/>REST controller"]
  node_osctl["OS<br/>REST controller"]
  node_finctl["Financeiro<br/>REST controller"]
end

subgraph group_async["Async"]
  node_asynccfg["Async cfg<br/>async config<br/>[AsyncConfig.java]"]
  node_clienteasync["Cliente async<br/>async service"]
  node_vendaasync["Venda async<br/>async service"]
end

subgraph group_service["Service"]
  node_clientesvc["Cliente svc<br/>business service"]
  node_vendasvc["Venda svc<br/>business service<br/>[VendaService.java]"]
  node_ossvc["OS svc<br/>business service"]
  node_finsvc["Finance svc<br/>business service"]
end

subgraph group_persistence["Persistence"]
  node_clienterepo["Cliente repo<br/>JPA repository"]
  node_vendarepo["Venda repo<br/>JPA repository"]
  node_osrepo["OS repo<br/>JPA repository"]
  node_finrepo["Finance repo<br/>JPA repository"]
end

subgraph group_domain["Domain"]
  node_clienteent["Cliente<br/>JPA entity<br/>[Cliente.java]"]
  node_vendaent["Venda<br/>JPA entity<br/>[Venda.java]"]
  node_osent["Ordem OS<br/>JPA entity<br/>[OrdemServico.java]"]
  node_finent["Movimento<br/>JPA entity"]
end

node_app -->|"starts with"| node_webconfig
node_webconfig -->|"uses"| node_apikeyconfig
node_apikeyconfig -->|"registers"| node_apikeyinterceptor
node_apikeyinterceptor -->|"rejects with"| node_apierror
node_webconfig -->|"opens"| node_publicctl
node_apikeyinterceptor -->|"protects"| node_clientectl
node_apikeyinterceptor -->|"protects"| node_vendactl
node_apikeyinterceptor -->|"protects"| node_osctl
node_apikeyinterceptor -->|"protects"| node_finctl
node_clientectl -->|"delegates"| node_clientesvc
node_vendactl -->|"delegates"| node_vendasvc
node_osctl -->|"delegates"| node_ossvc
node_finctl -->|"delegates"| node_finsvc
node_clientesvc -->|"persists via"| node_clienterepo
node_vendasvc -->|"persists via"| node_vendarepo
node_ossvc -->|"persists via"| node_osrepo
node_finsvc -->|"persists via"| node_finrepo
node_clienterepo -->|"maps"| node_clienteent
node_vendarepo -->|"maps"| node_vendaent
node_osrepo -->|"maps"| node_osent
node_finrepo -->|"maps"| node_finent
node_clientesvc -.->|"can offload to"| node_clienteasync
node_vendasvc -.->|"can offload to"| node_vendaasync
node_asynccfg -->|"enables"| node_clienteasync
node_asynccfg -->|"enables"| node_vendaasync

click node_app "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/ConcessionariaApplication.java"
click node_webconfig "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/WebConfig.java"
click node_apikeyconfig "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiKeyConfig.java"
click node_apikeyinterceptor "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiKeyAuthInterceptor.java"
click node_apierror "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiErrorResponse.java"
click node_publicctl "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/PublicController.java"
click node_clientectl "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/ClienteController.java"
click node_vendactl "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/VendaController.java"
click node_osctl "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/OrdemServicoController.java"
click node_finctl "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/MovimentacaoFinanceiraController.java"
click node_asynccfg "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/async/AsyncConfig.java"
click node_clienteasync "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/async/cliente/ClienteAsyncService.java"
click node_vendaasync "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/async/venda/VendaAsyncService.java"
click node_clientesvc "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/ClienteService.java"
click node_vendasvc "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/VendaService.java"
click node_ossvc "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/OrdemServicoService.java"
click node_finsvc "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/MovimentacaoFinanceiraService.java"
click node_clienterepo "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/ClienteRepository.java"
click node_vendarepo "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/VendaRepository.java"
click node_osrepo "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/OrdemServicoRepository.java"
click node_finrepo "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/MovimentacaoFinanceiraRepository.java"
click node_clienteent "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/Cliente.java"
click node_vendaent "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/Venda.java"
click node_osent "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/OrdemServico.java"
click node_finent "https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/MovimentacaoFinanceira.java"

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_app toneBlue
class node_webconfig,node_apikeyconfig,node_apikeyinterceptor,node_apierror,node_publicctl,node_clientectl,node_vendactl,node_osctl,node_finctl toneAmber
class node_asynccfg,node_clienteasync,node_vendaasync toneMint
class node_clientesvc,node_vendasvc,node_ossvc,node_finsvc toneRose
class node_clienterepo,node_vendarepo,node_osrepo,node_finrepo toneIndigo
class node_clienteent,node_vendaent,node_osent,node_finent toneTeal
```

## Components

### Runtime

Application bootstrap and configuration

- [App](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/ConcessionariaApplication.java): Spring Boot entrypoint · Main application bootstrap. · `src/main/java/com/grupo8/concessionaria/ConcessionariaApplication.java`

### API

HTTP entry points and request boundary

- [Web config](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/WebConfig.java): MVC config · Registers request interception and route handling rules. · `src/main/java/com/grupo8/concessionaria/config/WebConfig.java`
- [API key cfg](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiKeyConfig.java): security config · Defines API key security wiring and protected/public route boundaries. · `src/main/java/com/grupo8/concessionaria/config/ApiKeyConfig.java`
- [API key check](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiKeyAuthInterceptor.java): request interceptor · Validates x-api-key on protected routes. · `src/main/java/com/grupo8/concessionaria/config/ApiKeyAuthInterceptor.java`
- [API error](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/config/ApiErrorResponse.java): error payload · Standardized error response for auth failures and API errors. · `src/main/java/com/grupo8/concessionaria/config/ApiErrorResponse.java`
- [Public API](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/PublicController.java): public controller · Unauthenticated API surface. · `src/main/java/com/grupo8/concessionaria/controller/PublicController.java`
- [Clientes](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/ClienteController.java): REST controller · Customer endpoints. · `src/main/java/com/grupo8/concessionaria/controller/ClienteController.java`
- [Vendas](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/VendaController.java): REST controller · Sales endpoints. · `src/main/java/com/grupo8/concessionaria/controller/VendaController.java`
- [OS](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/OrdemServicoController.java): REST controller · Service order endpoints. · `src/main/java/com/grupo8/concessionaria/controller/OrdemServicoController.java`
- [Financeiro](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/controller/MovimentacaoFinanceiraController.java): REST controller · Financial movement endpoints. · `src/main/java/com/grupo8/concessionaria/controller/MovimentacaoFinanceiraController.java`

### Async

Background execution paths

- [Async cfg](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/async/AsyncConfig.java): async config · Enables asynchronous execution. · `src/main/java/com/grupo8/concessionaria/async/AsyncConfig.java`
- [Cliente async](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/async/cliente/ClienteAsyncService.java): async service · Background customer-related processing. · `src/main/java/com/grupo8/concessionaria/async/cliente/ClienteAsyncService.java`
- [Venda async](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/async/venda/VendaAsyncService.java): async service · Background sales-related processing. · `src/main/java/com/grupo8/concessionaria/async/venda/VendaAsyncService.java`

### Service

Business rules and orchestration

- [Cliente svc](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/ClienteService.java): business service · Customer rules and coordination. · `src/main/java/com/grupo8/concessionaria/model/service/ClienteService.java`
- [Venda svc](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/VendaService.java): business service · Sales workflow orchestration. · `src/main/java/com/grupo8/concessionaria/model/service/VendaService.java`
- [OS svc](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/OrdemServicoService.java): business service · Service order workflow orchestration. · `src/main/java/com/grupo8/concessionaria/model/service/OrdemServicoService.java`
- [Finance svc](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/service/MovimentacaoFinanceiraService.java): business service · Financial movement rules and coordination. · `src/main/java/com/grupo8/concessionaria/model/service/MovimentacaoFinanceiraService.java`

### Persistence

Spring Data repositories and database access

- [Cliente repo](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/ClienteRepository.java): JPA repository · Persistence access for customers. · `src/main/java/com/grupo8/concessionaria/model/repository/ClienteRepository.java`
- [Venda repo](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/VendaRepository.java): JPA repository · Persistence access for sales. · `src/main/java/com/grupo8/concessionaria/model/repository/VendaRepository.java`
- [OS repo](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/OrdemServicoRepository.java): JPA repository · Persistence access for service orders. · `src/main/java/com/grupo8/concessionaria/model/repository/OrdemServicoRepository.java`
- [Finance repo](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/repository/MovimentacaoFinanceiraRepository.java): JPA repository · Persistence access for financial movements. · `src/main/java/com/grupo8/concessionaria/model/repository/MovimentacaoFinanceiraRepository.java`

### Domain

Core entities and business state

- [Cliente](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/Cliente.java): JPA entity · Customer domain entity. · `src/main/java/com/grupo8/concessionaria/model/entities/Cliente.java`
- [Venda](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/Venda.java): JPA entity · Sale domain entity. · `src/main/java/com/grupo8/concessionaria/model/entities/Venda.java`
- [Ordem OS](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/OrdemServico.java): JPA entity · Service order domain entity. · `src/main/java/com/grupo8/concessionaria/model/entities/OrdemServico.java`
- [Movimento](https://github.com/unilopers/concessionaria/blob/main/src/main/java/com/grupo8/concessionaria/model/entities/MovimentacaoFinanceira.java): JPA entity · Financial movement domain entity. · `src/main/java/com/grupo8/concessionaria/model/entities/MovimentacaoFinanceira.java`

## Connections

- App → Web config: starts with · Application bootstraps MVC and security configuration.
- Web config → API key cfg: uses · Web config wires the API-key security boundary.
- API key cfg → API key check: registers · Security config installs the request interceptor.
- API key check → API error: rejects with · Invalid or missing keys are normalized into API errors.
- Web config → Public API: opens · Public routes remain outside the API-key gate.
- API key check → Clientes: protects · Protected business endpoints require a valid key.
- API key check → Vendas: protects · Protected business endpoints require a valid key.
- API key check → OS: protects · Protected business endpoints require a valid key.
- API key check → Financeiro: protects · Protected business endpoints require a valid key.
- Clientes → Cliente svc: delegates · Controller hands off business logic to the service layer.
- Vendas → Venda svc: delegates · Controller hands off business logic to the service layer.
- OS → OS svc: delegates · Controller hands off business logic to the service layer.
- Financeiro → Finance svc: delegates · Controller hands off business logic to the service layer.
- Cliente svc → Cliente repo: persists via · Customer service reads and writes through JPA.
- Venda svc → Venda repo: persists via · Sales service reads and writes through JPA.
- OS svc → OS repo: persists via · Service order service reads and writes through JPA.
- Finance svc → Finance repo: persists via · Financial service reads and writes through JPA.
- Cliente repo → Cliente: maps · Repository manages customer entities.
- Venda repo → Venda: maps · Repository manages sale entities.
- OS repo → Ordem OS: maps · Repository manages service order entities.
- Finance repo → Movimento: maps · Repository manages financial movement entities.
- Cliente svc → Cliente async: can offload to · Customer flows may branch into async processing.
- Venda svc → Venda async: can offload to · Sales flows may branch into async processing.
- Async cfg → Cliente async: enables · Async configuration activates background customer work.
- Async cfg → Venda async: enables · Async configuration activates background sales work.
