# psinalberth/algafood-api architecture

> Architecture diagram of the GitHub repository psinalberth/algafood-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psinalberth/algafood-api
- Repository: https://github.com/psinalberth/algafood-api

## Overview

##### Project Type and Purpose
- This is a monolithic Spring Boot REST API (“algafood-api”) that models a food-delivery platform (inspired by iFood/Uber Eats).
- It exposes JSON endpoints for managing entities like Restaurante, Cozinha (kitchen), Cidade, Pedido (order), Usuário, Permissões, estatísticas de vendas, etc.

##### High-Level Layered Architecture
The code is organized into four macro-layers inside one JVM process:
- Presentation/API layer
- Domain layer
- Application/Service layer
- Infrastructure/Persistence layer
Plus cross-cutting modules (security, email, storage, documentation).

##### Main Components
A. Clients & Entry Points
– External consumers (Web/Mobile apps, Postman, Swagger UI)
– Swagger/OpenAPI UI
B. API Layer
– Controllers (packages under `api/controller` & `api/openapi/controller`)
– Exception handlers (`api/exceptionhandler`)
– HATEOAS support (`api/AlgaLinks`)
C. Application Services
– Spring-managed services under `domain/service` (e.g., `CadastroPedidoService`, `RestauranteService`)
– Event publishers (domain events & listeners under `domain/event` + `domain/listener`)
D. Domain Model
– Entities (`domain/model`)
– Business rules & validators (`core/validation`)
– DTOs for reports (`domain/model/dto`)
E. Persistence
– Repositories (Spring Data JPA interfaces under `domain/repository`)
– Custom implementations (`infrastructure/repository`)
– Flyway migrations (`src/main/resources/db/migration`)
– ORM metadata (`META-INF/orm.xml`)
– MySQL database
F. Infrastructure Services
– Email (SMTP/Sandbox/Fake implementations under `infrastructure/service/email` + config in `core/email`)
– File storage (local & S3 under `infrastructure/service/storage` + config in `core/storage`)
– Reporting (Jasper under `infrastructure/service/report`)
G. Security & OAuth2
– Resource server (`core/security/ResourceServerConfig`, `CorsConfig`)
– Authorization server (`core/security/authorizationserver`), JWT signing keystore
H. Cross-cutting & Tooling
– MapStruct mappers (`api/model/mapper`)
– Jackson customization (`core/jackson`)
– Swagger/SpringFox integration (`core/springfox`)
– Application config (YAML, logging, message bundles)

##### Relationships and Data Flow
- Clients → Controllers → Services → Domain → Repositories → Database
- Controllers use Mappers to convert between domain objects and API DTOs
- Services publish domain events → Event listeners trigger email notifications or other side-effects
- Security filters intercept requests → validate JWTs via ResourceServerConfig → load users via JPA
- Storage calls go from Service → Local file system or AWS S3
- Reporting service queries data, hands off to Jasper, returns PDF to the client
- Flyway migrates schema before startup & loads test data in CI

##### Architectural Patterns and Principles
- Layered (hexagonal-inspired) architecture
- Dependency inversion: Controllers depend on Service interfaces; Services depend on Repository interfaces; infrastructure binds implementations
- Event-driven for decoupling side-effects (email notifications)
- DTO/mapper pattern for decoupling API model from domain
- Externalize configuration (YAML, properties) and secret material (keystore, Flyway)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Clients(["Clients (Web/Mobile/Swagger UI)"]):::external
    MySQL[(MySQL Database)]:::db
    S3[(AWS S3 Storage)]:::external
    SMTP[(SMTP Server)]:::external
    OAuth2Auth(["OAuth2 Authorization Server"]):::external

    %% Main Application Container
    subgraph "algafood-api (Spring Boot Application)"
        direction TB

        %% API Layer
        subgraph "API Layer" 
            direction TB
            Controllers(["Controllers\n(api/controller/)"]):::api
            OpenAPIControllers(["OpenAPI Controllers\n(api/openapi/controller/)"]):::api
            ExceptionHandlers(["Exception Handlers\n(api/exceptionhandler/)"]):::api
            HATEOAS(["HATEOAS Support\n(api/AlgaLinks)"]):::api
            Mappers(["DTO Mappers\n(api/model/mapper/)"]):::api
            RootEntry(["RootEntryPointController"]):::api
            SpringFox(["SpringFoxConfig"]):::api
        end

        %% Service Layer
        subgraph "Service Layer" 
            direction TB
            DomainServices(["Domain Services\n(domain/service/)"]):::service
            DomainEvents(["Domain Events & Listeners\n(domain/event/ & listener/)"]):::service
        end

        %% Domain Model
        subgraph "Domain Model"
            direction TB
            Entities(["Entities\n(domain/model/)"]):::domain
            Validation(["Validation\n(core/validation/)"]):::domain
            ReportDTOs(["Report DTOs\n(domain/model/dto/)"]):::domain
        end

        %% Repository Layer
        subgraph "Repository Layer"
            direction TB
            RepoInterfaces(["Repository Interfaces\n(domain/repository/)"]):::repo
            RepoImpl(["Custom Repositories\n(infrastructure/repository/)"]):::repo
            Flyway(["Flyway Migrations\n(db/migration/)"]):::repo
            ORMMeta(["ORM Metadata\n(META-INF/orm.xml)"]):::repo
        end

        %% Infrastructure
        subgraph "Infrastructure"
            direction TB
            subgraph "Email Service"
                EmailInfra(["Email Implementations\n(infrastructure/service/email/)"]):::infra
                EmailCore(["Email Config\n(core/email/)"]):::infra
            end
            subgraph "File Storage"
                StorageInfra(["Storage Implementations\n(infrastructure/service/storage/)"]):::infra
                StorageCore(["Storage Config\n(core/storage/)"]):::infra
            end
            subgraph "Reporting Service"
                Reporting(["Jasper Reports\n(infrastructure/service/report/)"]):::infra
            end
        end

        %% Security & Config
        subgraph "Security & Config"
            direction TB
            ResourceServer(["ResourceServerConfig"]):::infra
            CorsConfig(["CorsConfig"]):::infra
            AuthServerConfig(["Authorization Server\n(core/security/authorizationserver/)"]):::infra
            Keystore(["Keystore Files\n(keys/)"]):::infra
            Jackson(["CustomPageSerializer\n(core/jackson/)"]):::infra
            SpringFoxCore(["SpringFox Integration\n(core/springfox/)"]):::infra
            AppConfig(["YAML & Logging\n(application.yml, logback-spring.xml)"]):::infra
        end
    end

    %% Data Flows
    Clients -->|"HTTPS/JSON"| Controllers
    Clients --> SwaggerUI
    Controllers -->|"invoke business methods"| DomainServices
    Controllers -->|"map DTOs"| Mappers
    DomainServices -->|"validate & apply rules"| Entities
    DomainServices -->|"publish events"| DomainEvents
    DomainEvents -.->|"async listeners"| EmailInfra
    DomainEvents -.-> EmailInfra
    DomainServices -->|"CRUD via JPA"| RepoInterfaces
    RepoInterfaces --> RepoImpl
    RepoImpl --> MySQL
    DomainServices -->|"send email"| EmailInfra
    DomainServices -->|"store files"| StorageInfra
    DomainServices -->|"generate report"| Reporting
    Controllers --> ResourceServer
    ResourceServer -->|"validate JWT"| OAuth2Auth
    CorsConfig --> Controllers

    %% Click Events
    click RootEntry "https://github.com/psinalberth/algafood-api/blob/master/src/main/java/com/algaworks/algafood/api/controller/RootEntryPointController.java"
    click SpringFox "https://github.com/psinalberth/algafood-api/blob/master/src/main/java/com/algaworks/algafood/core/springfox/SpringFoxConfig.java"
    click Controllers "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/api/controller/"
    click OpenAPIControllers "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/api/openapi/controller/"
    click ExceptionHandlers "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/api/exceptionhandler/"
    click HATEOAS "https://github.com/psinalberth/algafood-api/blob/master/src/main/java/com/algaworks/algafood/api/AlgaLinks.java"
    click Mappers "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/api/model/mapper/"
    click DomainServices "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/domain/service/"
    click DomainEvents "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/domain/event/"
    click DomainEvents "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/domain/listener/"
    click Entities "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/domain/model/"
    click Validation "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/core/validation/"
    click ReportDTOs "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/domain/model/dto/"
    click RepoInterfaces "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/domain/repository/"
    click RepoImpl "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/infrastructure/repository/"
    click Flyway "https://github.com/psinalberth/algafood-api/tree/master/src/main/resources/db/migration/"
    click ORMMeta "https://github.com/psinalberth/algafood-api/blob/master/src/main/resources/META-INF/orm.xml"
    click EmailInfra "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/infrastructure/service/email/"
    click EmailCore "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/core/email/"
    click StorageInfra "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/infrastructure/service/storage/"
    click StorageCore "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/core/storage/"
    click Reporting "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/infrastructure/service/report/"
    click ResourceServer "https://github.com/psinalberth/algafood-api/blob/master/src/main/java/com/algaworks/algafood/core/security/ResourceServerConfig.java"
    click CorsConfig "https://github.com/psinalberth/algafood-api/blob/master/src/main/java/com/algaworks/algafood/core/security/CorsConfig.java"
    click AuthServerConfig "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/core/security/authorizationserver/"
    click Keystore "https://github.com/psinalberth/algafood-api/blob/master/src/main/resources/keys/algafood.jks"
    click Keystore "https://github.com/psinalberth/algafood-api/blob/master/src/main/resources/keys/algafood-pkey.pem"
    click Jackson "https://github.com/psinalberth/algafood-api/blob/master/src/main/java/com/algaworks/algafood/core/jackson/CustomPageSerializer.java"
    click SpringFoxCore "https://github.com/psinalberth/algafood-api/tree/master/src/main/java/com/algaworks/algafood/core/springfox/"
    click AppConfig "https://github.com/psinalberth/algafood-api/blob/master/src/main/resources/application.yml"
    click AppConfig "https://github.com/psinalberth/algafood-api/blob/master/src/main/resources/logback-spring.xml"
    click AppConfig "https://github.com/psinalberth/algafood-api/blob/master/src/main/resources/messages.properties"

    %% Styles
    classDef external fill:#ececec,stroke:#999,stroke-width:1px
    classDef api fill:#cfe2f3,stroke:#0366d6,stroke-width:2px
    classDef service fill:#d9ead3,stroke:#6aa84f,stroke-width:2px
    classDef domain fill:#fce5cd,stroke:#e69138,stroke-width:2px
    classDef repo fill:#dddddd,stroke:#666666,stroke-width:2px
    classDef db fill:#ffd966,stroke:#d17a00,stroke-width:2px
    classDef infra fill:#f2f2f2,stroke:#999999,stroke-width:2px
```
