# shcoide/arl-trays-api architecture

> Architecture diagram of the GitHub repository shcoide/arl-trays-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shcoide/arl-trays-api
- Repository: https://github.com/shcoide/arl-trays-api

## Overview

ARL Trays API tracks trays and batches from seeding through growth stages to harvest. The main workflow is an HTTP client request entering Fastify, passing route validation, invoking a domain service, and reading or writing PostgreSQL; batch progression is enforced one step at a time, with harvest as a transactional final operation. The README documents filtering, concurrency protections, and error behavior. Some wiring is based on the README because the full database schema and tray service implementation were not sampled.

Main entry points: [`src/app.ts`](https://github.com/shcoide/arl-trays-api/blob/main/src/app.ts) (Fastify app), [`src/routes/trays.ts`](https://github.com/shcoide/arl-trays-api/blob/main/src/routes/trays.ts) (Tray routes), [`src/routes/batches.ts`](https://github.com/shcoide/arl-trays-api/blob/main/src/routes/batches.ts) (Batch routes), [`src/services/batches.ts`](https://github.com/shcoide/arl-trays-api/blob/main/src/services/batches.ts) (Batch service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["API server<br/>[index.ts]"]
  node_app["Fastify app<br/>[app.ts]"]
  node_schemas["Request schemas<br/>[schemas.ts]"]
  node_errors["HTTP errors<br/>[errors.ts]"]
end

subgraph group_tray["Tray Management"]
  node_tray_routes["Tray routes<br/>[trays.ts]"]
  node_tray_service["Tray service<br/>[trays.ts]"]
end

subgraph group_batch["Batch Lifecycle"]
  node_batch_routes["Batch routes<br/>[batches.ts]"]
  node_batch_service["Batch service<br/>[batches.ts]"]
  node_stages["Stage ordering<br/>[stages.ts]"]
end

subgraph group_persistence["Persistence"]
  node_pool["Postgres pool<br/>[db.ts]"]
  node_database[("PostgreSQL")]
  node_schema["Data schema<br/>[schema.sql]"]
end

node_client(("HTTP client"))

node_client -->|"sends requests"| node_server
node_server -->|"builds and listens"| node_app
node_app -->|"registers routes"| node_tray_routes
node_app -->|"registers routes"| node_batch_routes
node_tray_routes -->|"validates input"| node_schemas
node_batch_routes -->|"validates input"| node_schemas
node_tray_routes -->|"dispatches"| node_tray_service
node_batch_routes -->|"dispatches"| node_batch_service
node_batch_service -->|"computes next stage"| node_stages
node_tray_service -->|"queries"| node_pool
node_batch_service -->|"queries"| node_pool
node_pool -->|"connects"| node_database
node_schema -->|"defines tables and constraints"| node_database
node_app -->|"maps HTTP errors"| node_errors

click node_server "https://github.com/shcoide/arl-trays-api/blob/main/src/index.ts"
click node_app "https://github.com/shcoide/arl-trays-api/blob/main/src/app.ts"
click node_schemas "https://github.com/shcoide/arl-trays-api/blob/main/src/schemas.ts"
click node_errors "https://github.com/shcoide/arl-trays-api/blob/main/src/errors.ts"
click node_tray_routes "https://github.com/shcoide/arl-trays-api/blob/main/src/routes/trays.ts"
click node_tray_service "https://github.com/shcoide/arl-trays-api/blob/main/src/services/trays.ts"
click node_batch_routes "https://github.com/shcoide/arl-trays-api/blob/main/src/routes/batches.ts"
click node_batch_service "https://github.com/shcoide/arl-trays-api/blob/main/src/services/batches.ts"
click node_stages "https://github.com/shcoide/arl-trays-api/blob/main/src/stages.ts"
click node_pool "https://github.com/shcoide/arl-trays-api/blob/main/src/db.ts"
click node_schema "https://github.com/shcoide/arl-trays-api/blob/main/db/schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_app,node_schemas,node_errors,node_client toneBlue
class node_tray_routes,node_tray_service toneAmber
class node_batch_routes,node_batch_service,node_stages toneMint
class node_pool,node_database,node_schema toneRose
```

## Components

### HTTP API

- [API server](https://github.com/shcoide/arl-trays-api/blob/main/src/index.ts): `src/index.ts`
- [Fastify app](https://github.com/shcoide/arl-trays-api/blob/main/src/app.ts): `src/app.ts`
- [Request schemas](https://github.com/shcoide/arl-trays-api/blob/main/src/schemas.ts): `src/schemas.ts`
- [HTTP errors](https://github.com/shcoide/arl-trays-api/blob/main/src/errors.ts): `src/errors.ts`

### Tray Management

- [Tray routes](https://github.com/shcoide/arl-trays-api/blob/main/src/routes/trays.ts): `src/routes/trays.ts`
- [Tray service](https://github.com/shcoide/arl-trays-api/blob/main/src/services/trays.ts): `src/services/trays.ts`

### Batch Lifecycle

- [Batch routes](https://github.com/shcoide/arl-trays-api/blob/main/src/routes/batches.ts): `src/routes/batches.ts`
- [Batch service](https://github.com/shcoide/arl-trays-api/blob/main/src/services/batches.ts): `src/services/batches.ts`
- [Stage ordering](https://github.com/shcoide/arl-trays-api/blob/main/src/stages.ts): `src/stages.ts`

### Persistence

- [Postgres pool](https://github.com/shcoide/arl-trays-api/blob/main/src/db.ts): `src/db.ts`
- **PostgreSQL**
- [Data schema](https://github.com/shcoide/arl-trays-api/blob/main/db/schema.sql): `db/schema.sql`

### Other components

- **HTTP client**

## Connections

- HTTP client → API server: sends requests
- API server → Fastify app: builds and listens
- Fastify app → Tray routes: registers routes
- Fastify app → Batch routes: registers routes
- Tray routes → Request schemas: validates input
- Batch routes → Request schemas: validates input
- Tray routes → Tray service: dispatches
- Batch routes → Batch service: dispatches
- Batch service → Stage ordering: computes next stage
- Tray service → Postgres pool: queries
- Batch service → Postgres pool: queries
- Postgres pool → PostgreSQL: connects
- Data schema → PostgreSQL: defines tables and constraints
- Fastify app → HTTP errors: maps HTTP errors