How jorge-vasquez-2301/zio-backend-example works
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