# jorge-vasquez-2301/zio-backend-example architecture

> Architecture diagram of the GitHub repository jorge-vasquez-2301/zio-backend-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jorge-vasquez-2301/zio-backend-example
- Repository: https://github.com/jorge-vasquez-2301/zio-backend-example

## Overview

##### Project Type and Purpose
- This is a standalone back-end REST API service written in Scala 3.
- It exposes CRUD endpoints for managing Departments, Employees, Phones, and Employee-Phone relationships.
- It leverages ZIO HTTP for the server, Magnum (SQL/table definitions), Iron (type refinement/validation), and Testcontainers (integration testing).

##### File Structure Analysis
- src/main/scala/com/example
- api/router: defines the HTTP router and mounts endpoints
- api/endpoint: request/response codecs and endpoint definitions
- api/handler: business request handlers that translate HTTP calls into service calls
- service: application-level services implementing use-case logic
- repository: database access interfaces and implementations
- tables: table schemas for Magnum (mapping to physical tables)
- domain: core domain models (IDs, names, refined types)
- util: shared givens (typeclass instances, implicits)
- error: custom error ADTs
- project & build.sbt: SBT configuration, plugin definitions
- README.md: overview of libraries and purpose

##### Architectural Patterns and Layers
- Hexagonal / Onion-style layering
- Outer Adapter Layer: HTTP server and request/response layer (ZIO HTTP)
- Application Layer: Router → Endpoint → Handler → Service
- Domain Layer: pure domain models, refinement types (Iron)
- Infrastructure Layer: Repository implementations, Magnum table mappings, actual DB (PostgreSQL or similar)
- Each layer depends only on the one immediately beneath it.

##### Main Components
a. HTTP Server (ZIO HTTP)
b. Router (Router.scala)
c. Endpoints (Codecs + DepartmentEndpoints, EmployeeEndpoints, etc.)
d. Handlers (DepartmentHandlers, EmployeeHandlers, …)
e. Services (DepartmentService, EmployeeService, …)
f. Repositories (DepartmentRepository, EmployeeRepository, …)
i. External/Test Components: Testcontainers for spinning up DB during tests

##### Component Relationships and Data Flow
1. Incoming HTTP Request → ZIO HTTP Server
2. Server forwards to Router
3. Router dispatches to the matching Endpoint (with request decoding via Codecs)
4. Endpoint invokes the corresponding Handler
5. Handler calls into the Service layer (business logic)
6. Service uses Repository interfaces to fetch/persist data
7. Repository implementations use Magnum table mappings to execute SQL on the Database
8. Data returns back up the chain → Handler → Endpoint → HTTP Response

##### Key Technologies and Roles
- ZIO HTTP: HTTP server & routing
- Iron: domain-level refined types and compile-time validation
- Magnum: DSL for table definitions and SQL generation
- Testcontainers: spin up real DB instance for integration tests
- SBT & Scala 3: build tool and language

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Adapter Layer
    subgraph "API Adapter Layer"
        direction TB
        HTTP["HTTP Server\n(ZIO HTTP)"]:::api
        Router["Router\n(com.example.api.Router)"]:::api
        subgraph Endpoints
            direction TB
            Codecs["Codecs\n(request/response codecs)"]:::api
            DeptEP["DepartmentEndpoints"]:::api
            EmpEP["EmployeeEndpoints"]:::api
            PhoneEP["PhoneEndpoints"]:::api
            EmpPhoneEP["EmployeePhoneEndpoints"]:::api
        end
        subgraph Handlers
            direction TB
            DeptH["DepartmentHandlers"]:::api
            EmpH["EmployeeHandlers"]:::api
            PhoneH["PhoneHandlers"]:::api
            EmpPhoneH["EmployeePhoneHandlers"]:::api
        end
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        DeptS["DepartmentService"]:::app
        EmpS["EmployeeService"]:::app
        PhoneS["PhoneService"]:::app
        EmpPhoneS["EmployeePhoneService"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DomainModels["Domain Models\n(Iron Refined Types)"]:::domain
        ErrorADT["Error ADTs"]:::domain
        Util["Utilities\n(givens)"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        subgraph Repositories
            direction TB
            DeptR["DepartmentRepository"]:::infra
            EmpR["EmployeeRepository"]:::infra
            PhoneR["PhoneRepository"]:::infra
            EmpPhoneR["EmployeePhoneRepository"]:::infra
        end
        subgraph Tables
            direction TB
            DeptT["Department Table"]:::infra
            EmpT["Employee Table"]:::infra
            PhoneT["Phone Table"]:::infra
            EmpPhoneT["EmployeePhone Table"]:::infra
        end
        DB["Database\n(PostgreSQL)"]:::infra
    end

    %% Testing
    Test["Testcontainers\n(DB for Tests)"]:::external

    %% Connections
    HTTP -->|"incoming request"| Router
    Router -->|"routes to"| DeptEP
    Router -->|"routes to"| EmpEP
    Router -->|"routes to"| PhoneEP
    Router -->|"routes to"| EmpPhoneEP

    DeptEP -->|"decode via Codecs"| Codecs
    EmpEP -->|"decode via Codecs"| Codecs
    PhoneEP -->|"decode via Codecs"| Codecs
    EmpPhoneEP -->|"decode via Codecs"| Codecs

    DeptEP -->|"calls"| DeptH
    EmpEP -->|"calls"| EmpH
    PhoneEP -->|"calls"| PhoneH
    EmpPhoneEP -->|"calls"| EmpPhoneH

    DeptH -->|"invokes"| DeptS
    EmpH -->|"invokes"| EmpS
    PhoneH -->|"invokes"| PhoneS
    EmpPhoneH -->|"invokes"| EmpPhoneS

    DeptS -->|"uses"| DeptR
    EmpS -->|"uses"| EmpR
    PhoneS -->|"uses"| PhoneR
    EmpPhoneS -->|"uses"| EmpPhoneR

    DeptR -->|"maps via Magnum"| DeptT
    EmpR -->|"maps via Magnum"| EmpT
    PhoneR -->|"maps via Magnum"| PhoneT
    EmpPhoneR -->|"maps via Magnum"| EmpPhoneT

    DeptT -->|"SQL ops"| DB
    EmpT -->|"SQL ops"| DB
    PhoneT -->|"SQL ops"| DB
    EmpPhoneT -->|"SQL ops"| DB

    DB -->|"data"| DeptS
    DB -->|"data"| EmpS
    DB -->|"data"| PhoneS
    DB -->|"data"| EmpPhoneS

    Test -.->|"spins up"| DB

    %% Click Events
    click HTTP "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/Main.scala"
    click Router "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/Router.scala"
    click Codecs "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/endpoint/Codecs.scala"
    click DeptEP "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/endpoint/DepartmentEndpoints.scala"
    click EmpEP "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/endpoint/EmployeeEndpoints.scala"
    click PhoneEP "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/endpoint/PhoneEndpoints.scala"
    click EmpPhoneEP "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/endpoint/EmployeePhoneEndpoints.scala"
    click DeptH "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/handler/DepartmentHandlers.scala"
    click EmpH "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/handler/EmployeeHandlers.scala"
    click PhoneH "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/handler/PhoneHandlers.scala"
    click EmpPhoneH "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/api/handler/EmployeePhoneHandlers.scala"
    click DeptS "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/service/DepartmentService.scala"
    click EmpS "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/service/EmployeeService.scala"
    click PhoneS "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/service/PhoneService.scala"
    click EmpPhoneS "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/service/EmployeePhoneService.scala"
    click DeptR "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/repository/DepartmentRepository.scala"
    click EmpR "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/repository/EmployeeRepository.scala"
    click PhoneR "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/repository/PhoneRepository.scala"
    click EmpPhoneR "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/repository/EmployeePhoneRepository.scala"
    click DeptT "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/tables/Department.scala"
    click EmpT "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/tables/Employee.scala"
    click PhoneT "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/tables/Phone.scala"
    click EmpPhoneT "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/tables/EmployeePhone.scala"
    click DomainModels "https://github.com/jorge-vasquez-2301/zio-backend-example/tree/main/src/main/scala/com/example/domain"
    click ErrorADT "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/error/Error.scala"
    click Util "https://github.com/jorge-vasquez-2301/zio-backend-example/blob/main/src/main/scala/com/example/util/givens.scala"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#5DADE2,color:#1B4F72
    classDef app fill:#FDEBD0,stroke:#F5B041,color:#7D6608
    classDef domain fill:#D5F5E3,stroke:#52BE80,color:#145A32
    classDef infra fill:#F4F6F7,stroke:#BFC9CA,color:#424949
    classDef external fill:#F9E79F,stroke:#F4D03F,color:#7E5109
```
