# lbbedendo/diecast-collector-api architecture

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

- Interactive diagram: https://gitdiagram.com/lbbedendo/diecast-collector-api
- Repository: https://github.com/lbbedendo/diecast-collector-api

## Overview

##### Project Type & Purpose
- This is a backend REST API (“Diecast Collector API”) built with the Micronaut Framework in Java.
- Its purpose is to manage a diecast car collection (Automakers, Brands, Collections, Models) and expose CRUD‐style endpoints plus a dashboard.

##### Key Architectural Characteristics
- Layered architecture (Controller → Service → Repository → Database)
- Dependency Injection via Micronaut
- Database migrations via Flyway
- Typesafe SQL via jOOQ code generation during the Gradle build
- Deployment in Docker (Dockerfile + docker‐compose.yaml)
- Integration tests using Testcontainers

##### Main Components
A. Client Layer
- React Web App (or Insomnia/API client)
B. API Layer
- Micronaut HTTP Server
- Controllers:
– AutomakerController
– BrandController
– CollectionController
– ModelController
– DashboardController
- DTOs & Filters (request/response objects)
C. Business Logic Layer
- Services: AutomakerService, BrandService, CollectionService, ModelService, DashboardService
D. Data Access Layer
- Micronaut Data Repositories: AutomakerRepository, BrandRepository, CollectionRepository, ModelRepository
- jOOQ generated classes
E. Persistence
- PostgreSQL database
- Flyway migrations (V2__ddl.sql located under src/main/resources/db/migration)
F. Build & Deployment
- Gradle wrapper & build.gradle
- Docker: Dockerfile + docker-compose.yaml (PostgreSQL + App container)
- Testcontainers for integration tests

##### Relationships & Data Flow
1) Client issues HTTP requests →
2) Micronaut Router dispatches to the appropriate Controller →
3) Controller transforms request into DTOs and invokes Service →
4) Service encapsulates business rules and calls Repository →
5) Repository (Micronaut Data or jOOQ) executes SQL against PostgreSQL →
6) Flyway runs DB migrations at startup →
7) Response returns back up the chain to the client.

##### Architectural Patterns & Principles
- Layered Separation of Concerns (Controller / Service / Repository)
- Configuration‐as‐Code (application.yml, micronaut-cli.yml)
- Convention over Configuration via Micronaut
- Continuous Integration via Gradle and Docker
- Test Isolation with Testcontainers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        React["React Web App"]:::external
        Insomnia["Insomnia/API Client"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        Application["Micronaut Application Entry Point"]:::api
        subgraph "Controllers"
            AutomakerController["AutomakerController"]:::api
            BrandController["BrandController"]:::api
            CollectionController["CollectionController"]:::api
            ModelController["ModelController"]:::api
            DashboardController["DashboardController"]:::api
        end
        subgraph "DTOs & Filters"
            AutomakerSaveRequest["AutomakerSaveRequest"]:::api
            BrandSaveRequest["BrandSaveRequest"]:::api
            CollectionSaveRequest["CollectionSaveRequest"]:::api
            ModelSaveRequest["ModelSaveRequest"]:::api
            AutomakerFilters["AutomakerFilters"]:::api
            ModelQuantityByAutomakerResponse["ModelQuantityByAutomakerResponse"]:::api
            ModelQuantityByCollectionResponse["ModelQuantityByCollectionResponse"]:::api
            ModelsDashboardResponse["ModelsDashboardResponse"]:::api
        end
    end

    %% Business Logic Layer
    subgraph "Service Layer"
        AutomakerService["AutomakerService"]:::service
        BrandService["BrandService"]:::service
        CollectionService["CollectionService"]:::service
        ModelService["ModelService"]:::service
        DashboardService["DashboardService"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        AutomakerRepository["AutomakerRepository"]:::data
        BrandRepository["BrandRepository"]:::data
        CollectionRepository["CollectionRepository"]:::data
        ModelRepository["ModelRepository"]:::data
    end

    %% Infrastructure
    subgraph "Infrastructure"
        DB["PostgreSQL Database"]:::infra
        Flyway["Flyway Migrations"]:::infra
        Gradle["Gradle Build & jOOQ Code Generation"]:::infra
        DockerCompose["Docker Compose Orchestration"]:::infra
        Dockerfile["Dockerfile"]:::infra
        Testcontainers["Testcontainers (Integration Tests)"]:::infra
        ApplicationYml["application.yml"]:::infra
    end

    %% Relationships & Data Flow
    React -->|"HTTP Request"| Application
    Insomnia -->|"HTTP Request"| Application
    Application -->|"dispatch"| AutomakerController
    Application -->|"dispatch"| BrandController
    Application -->|"dispatch"| CollectionController
    Application -->|"dispatch"| ModelController
    Application -->|"dispatch"| DashboardController

    AutomakerController -->|"to DTO"| AutomakerSaveRequest
    BrandController -->|"to DTO"| BrandSaveRequest
    CollectionController -->|"to DTO"| CollectionSaveRequest
    ModelController -->|"to DTO"| ModelSaveRequest
    AutomakerController -->|"apply filters"| AutomakerFilters
    DashboardController -->|"compose response"| ModelsDashboardResponse

    AutomakerController -->|"invoke"| AutomakerService
    BrandController -->|"invoke"| BrandService
    CollectionController -->|"invoke"| CollectionService
    ModelController -->|"invoke"| ModelService
    DashboardController -->|"invoke"| DashboardService

    AutomakerService -->|"call repo"| AutomakerRepository
    BrandService -->|"call repo"| BrandRepository
    CollectionService -->|"call repo"| CollectionRepository
    ModelService -->|"call repo"| ModelRepository

    AutomakerRepository -->|"SQL SELECT/INSERT"| DB
    BrandRepository -->|"SQL SELECT/INSERT"| DB
    CollectionRepository -->|"SQL SELECT/INSERT"| DB
    ModelRepository -->|"SQL SELECT/INSERT"| DB

    Gradle -->|"- build time"| Flyway
    Gradle -->|"- codegen"| Gradle
    Flyway -.->|"migrate"| DB
    Gradle -.->|"generate jOOQ classes"| AutomakerRepository
    DockerCompose -->|"start"| Application
    DockerCompose -->|"start"| DB
    Testcontainers -->|"spawn DB"| DB

    %% Click Events
    click Application "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/Application.java"
    click AutomakerController "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/controller/AutomakerController.java"
    click BrandController "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/controller/BrandController.java"
    click CollectionController "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/controller/CollectionController.java"
    click ModelController "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/controller/ModelController.java"
    click DashboardController "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/controller/DashboardController.java"
    click AutomakerSaveRequest "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/AutomakerSaveRequest.java"
    click BrandSaveRequest "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/BrandSaveRequest.java"
    click CollectionSaveRequest "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/CollectionSaveRequest.java"
    click ModelSaveRequest "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/ModelSaveRequest.java"
    click AutomakerFilters "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/filters/AutomakerFilters.java"
    click ModelQuantityByAutomakerResponse "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/response/ModelQuantityByAutomakerResponse.java"
    click ModelQuantityByCollectionResponse "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/response/ModelQuantityByCollectionResponse.java"
    click ModelsDashboardResponse "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/dto/response/ModelsDashboardResponse.java"
    click AutomakerService "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/service/AutomakerService.java"
    click BrandService "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/service/BrandService.java"
    click CollectionService "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/service/CollectionService.java"
    click ModelService "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/service/ModelService.java"
    click DashboardService "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/service/DashboardService.java"
    click AutomakerRepository "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/repository/AutomakerRepository.java"
    click BrandRepository "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/repository/BrandRepository.java"
    click CollectionRepository "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/repository/CollectionRepository.java"
    click ModelRepository "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/java/diecast/collector/api/repository/ModelRepository.java"
    click Flyway "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/resources/db/migration/V2__ddl.sql"
    click ApplicationYml "https://github.com/lbbedendo/diecast-collector-api/blob/master/src/main/resources/application.yml"
    click Dockerfile "https://github.com/lbbedendo/diecast-collector-api/tree/master/Dockerfile"
    click DockerCompose "https://github.com/lbbedendo/diecast-collector-api/blob/master/docker-compose.yaml"
    click Gradle "https://github.com/lbbedendo/diecast-collector-api/blob/master/build.gradle"

    %% Styles
    classDef api fill:#cce5ff,stroke:#0066cc,color:#000
    classDef service fill:#d4edda,stroke:#28a745,color:#000
    classDef data fill:#fff3cd,stroke:#ffc107,color:#000
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef external fill:#f5c6cb,stroke:#c82333,color:#000
```
