# gemacjr/quarkus-todo architecture

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

- Interactive diagram: https://gitdiagram.com/gemacjr/quarkus-todo
- Repository: https://github.com/gemacjr/quarkus-todo

## Overview

##### Project type and purpose
- This is a standalone backend service: a RESTful CRUD API (“Todo API”) built with Quarkus (Java 17).
- It exposes HTTP endpoints (Create/Read/Update/Delete) for “todo” items, uses Hibernate ORM (Panache) for persistence, supports H2 (dev) and PostgreSQL (prod), and ships with Swagger UI, health checks, metrics, and Docker containerization.

##### File structure
- Top‐level:
- Docker-related files (Dockerfile, docker-compose.yml, src/main/docker/*.Dockerfile.*)
- Maven wrapper and pom.xml (build tool and dependency management)
- README.md (project overview)
- src/main/java/com/swiftbeard/… follows a classic layered MVC‐style layout:
- resource/         → JAX-RS REST endpoints
- service/          → business logic
- mapper/           → DTO ↔ Entity conversions
- dto/              → API data transfer objects
- model/            → JPA entities
- exception/        → global error handling
- src/main/resources/application.properties (configuration)
- src/test/… (JUnit 5 + REST Assured integration tests)

##### README for additional insights
- Tech stack calls out Quarkus, Hibernate Panache, PostgreSQL/H2, SmallRye OpenAPI, CDI, Hibernate Validator, JUnit5, Docker, Docker Compose.
- Features: health checks, metrics, Swagger docs, native builds via GraalVM.
- Docker Compose ties together the API container and a PostgreSQL container on a shared network.

##### Detail is key
- Architectural elements: HTTP interface, business logic, persistence, configuration, observability (metrics/health), documentation (Swagger), containerization, and testing.
- Lay out components in “lanes” or “tiers” (e.g., Client Tier, Application Tier, Data Tier, Infra Tier).
- Special features: H2 vs. PostgreSQL profiles, native executable build, health/metrics endpoints on /q/health and /q/metrics, and Swagger UI endpoint.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        Client["Clients\n(Browser, CLI, Postman)"]:::client
    end

    %% Application Tier
    subgraph "Application Tier"
        direction TB
        Resource["TodoResource\n(JAX-RS)"]:::api
        Service["TodoService\n(Business Logic)"]:::service
        Mapper["TodoMapper\n(DTO ↔ Entity)"]:::mapper
        DTO["TodoDto\n(API DTO)"]:::dto
        Model["Todo\n(JPA Entity & Panache)"]:::model
        ExceptionHandler["GlobalExceptionHandler"]:::exception
        ErrorResponse["ErrorResponse"]:::exception
        Config["application.properties"]:::config
        Swagger["Swagger UI / OpenAPI"]:::doc
        Health["Health & Metrics\n(/q/health, /q/metrics)"]:::obs
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        Postgres["PostgreSQL DB"]:::db
        H2["H2 DB"]:::db
    end

    %% Infra Tier
    subgraph "Infra Tier"
        direction TB
        DockerCompose["Docker Compose\nNetwork"]:::infra
        Dockerfiles["Dockerfiles\n(jvm, native, legacy)"]:::infra
        Maven["Maven\n(pom.xml, wrapper)"]:::infra
        Tests["Integration Tests\n(JUnit5 + REST Assured)"]:::tests
    end

    %% Relationships
    Client -->|HTTP Request| Resource
    Resource -->|calls| Service
    Service -->|uses| Mapper
    Service -->|uses| DTO
    Mapper -->|maps| Model
    Service -->|accesses| Model
    Model -->|persist| Postgres
    Model -->|persist| H2
    Resource -.->|handles| ExceptionHandler
    ExceptionHandler -->|formats| ErrorResponse
    Resource -->|serves| Swagger
    Resource -->|exposes| Health
    Config -->|configures| Resource
    Config -->|configures| Model
    Config -->|configures| Swagger
    Config -->|configures| Health
    DockerCompose -->|connects| Resource
    DockerCompose -->|connects| Postgres
    Dockerfiles -.->|builds images| DockerCompose
    Maven -.->|builds artifacts| Dockerfiles
    Tests -->|validate| Resource

    %% Click Events
    click Resource "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/resource/TodoResource.java"
    click Service "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/service/TodoService.java"
    click Mapper "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/mapper/TodoMapper.java"
    click DTO "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/dto/TodoDto.java"
    click Model "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/model/Todo.java"
    click ExceptionHandler "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/exception/GlobalExceptionHandler.java"
    click ErrorResponse "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/java/com/swiftbeard/exception/ErrorResponse.java"
    click Config "https://github.com/gemacjr/quarkus-todo/blob/main/src/main/resources/application.properties"

    %% Styles
    classDef client fill:#D6E9F8,stroke:#31708F,stroke-width:2px
    classDef api fill:#B9DEF0,stroke:#31708F,stroke-width:2px
    classDef service fill:#CDE2CD,stroke:#3C763D,stroke-width:2px
    classDef mapper fill:#CDE2CD,stroke:#3C763D,stroke-width:2px
    classDef dto fill:#CDE2CD,stroke:#3C763D,stroke-width:2px
    classDef model fill:#F2DEDE,stroke:#A94442,stroke-width:2px
    classDef exception fill:#F2DEDE,stroke:#A94442,stroke-width:2px
    classDef config fill:#FCF8E3,stroke:#8A6D3B,stroke-width:2px
    classDef doc fill:#D9EDF7,stroke:#31708F,stroke-width:2px
    classDef obs fill:#D9EDF7,stroke:#31708F,stroke-width:2px
    classDef db fill:#FAF2CC,stroke:#8A6D3B,stroke-width:2px
    classDef infra fill:#EEEEEE,stroke:#AAAAAA,stroke-dasharray:5 5
    classDef tests fill:#F5F5F5,stroke:#444444,stroke-width:2px
```
