# aom19/agri-api architecture

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

- Interactive diagram: https://gitdiagram.com/aom19/agri-api
- Repository: https://github.com/aom19/agri-api

## Overview

agri-api is a REST backend for agricultural operations and farm-resource management. Users authenticate, then call permission-protected APIs for fields, crops, machinery, assignments, field operations, inventory, dashboards, and reports; handlers delegate business rules to use cases and persistence to PostgreSQL repositories. Authentication also uses JWTs, Redis token blacklisting, refresh-token storage, and email. Background monitors track overdue operations, weather snapshots, and scheduled report digests. The tree and excerpts establish these subsystems, but many individual wiring details are unsampled; uncertain connections are shown as dashed.

Main entry points: [`internal/delivery/http/handlers`](https://github.com/aom19/agri-api/tree/main/internal/delivery/http/handlers) (API handlers), [`internal/repository/postgres`](https://github.com/aom19/agri-api/tree/main/internal/repository/postgres) (Postgres repositories), [`cmd/api/main.go`](https://github.com/aom19/agri-api/blob/main/cmd/api/main.go) (Server startup), [`internal/usecase/auth_service.go`](https://github.com/aom19/agri-api/blob/main/internal/usecase/auth_service.go) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["Server startup<br/>[main.go]"]
  node_router["HTTP routes<br/>[router.go]"]
  node_handlers["API handlers"]
  node_middleware["Auth middleware<br/>[auth.go]"]
end

subgraph group_business["Agricultural workflows"]
  node_ops["Field operations"]
  node_completion["Operation completion"]
  node_crops["Crop management<br/>[crop_service.go]"]
  node_equipment["Farm equipment"]
  node_reports["Reporting<br/>[report_service.go]"]
  node_reportdomain["Report models<br/>[report.go]"]
  node_weather["Weather service<br/>[weather_service.go]"]
  node_inventory["Resources and stock"]
  node_notifications["Notifications"]
end

subgraph group_data["Persistence"]
  node_store["Repository store<br/>[store.go]"]
  node_pgrepos["Postgres repositories"]
  node_postgres[("PostgreSQL<br/>[postgres.go]")]
end

subgraph group_identity["Identity and messaging"]
  node_authservice["Authentication<br/>[auth_service.go]"]
  node_jwt["JWT service<br/>[jwt_service.go]"]
  node_refresh["Refresh tokens<br/>[refresh_service.go]"]
  node_blacklist["Token blacklist<br/>[blacklist.go]"]
  node_email["Email delivery<br/>[service.go]"]
  node_redis[("Redis<br/>[client.go]")]
end

subgraph group_background["Background services"]
  node_overdue["Overdue monitor"]
  node_snapshots["Weather snapshots"]
  node_digest["Report digests"]
end

node_client(("API client"))
node_meteo["Open-Meteo"]
node_smtp["SMTP server"]

node_client -->|"sends requests"| node_router
node_entry -.->|"registers routes"| node_router
node_router -->|"routes requests"| node_handlers
node_router -->|"protects API"| node_middleware
node_handlers -.->|"invokes auth"| node_authservice
node_handlers -.->|"invokes operations"| node_ops
node_handlers -->|"completes work"| node_completion
node_handlers -.->|"invokes crop logic"| node_crops
node_handlers -.->|"invokes assignments"| node_equipment
node_handlers -.->|"requests reports"| node_reports
node_handlers -.->|"manages stock"| node_inventory
node_handlers -.->|"manages notifications"| node_notifications
node_middleware -.->|"validates tokens"| node_jwt
node_middleware -.->|"checks blacklist"| node_blacklist
node_authservice -->|"issues tokens"| node_jwt
node_authservice -->|"stores refresh tokens"| node_refresh
node_authservice -->|"revokes tokens"| node_blacklist
node_authservice -->|"sends account mail"| node_email
node_ops -.->|"persists operations"| node_pgrepos
node_completion -.->|"records completion"| node_pgrepos
node_crops -.->|"persists crops"| node_pgrepos
node_equipment -.->|"persists assignments"| node_pgrepos
node_reports -.->|"queries reports"| node_pgrepos
node_reports -->|"builds report models"| node_reportdomain
node_inventory -.->|"persists inventory"| node_pgrepos
node_pgrepos -.->|"reads and writes"| node_postgres
node_store -.->|"aggregates repositories"| node_pgrepos
node_entry -->|"starts monitor"| node_overdue
node_entry -->|"starts monitor"| node_snapshots
node_entry -->|"starts digest job"| node_digest
node_overdue -.->|"checks overdue work"| node_pgrepos
node_snapshots -.->|"fetches conditions"| node_weather
node_snapshots -.->|"stores snapshots"| node_pgrepos
node_weather -.->|"fetches forecasts"| node_meteo
node_digest -->|"generates digests"| node_reports
node_digest -.->|"sends summaries"| node_email
node_email -->|"sends mail"| node_smtp
node_entry -.->|"opens connection"| node_postgres
node_entry -.->|"initializes client"| node_redis

click node_entry "https://github.com/aom19/agri-api/blob/main/cmd/api/main.go"
click node_router "https://github.com/aom19/agri-api/blob/main/internal/delivery/http/router.go"
click node_handlers "https://github.com/aom19/agri-api/tree/main/internal/delivery/http/handlers"
click node_middleware "https://github.com/aom19/agri-api/blob/main/internal/delivery/http/middleware/auth.go"
click node_authservice "https://github.com/aom19/agri-api/blob/main/internal/usecase/auth_service.go"
click node_jwt "https://github.com/aom19/agri-api/blob/main/internal/auth/jwt_service.go"
click node_refresh "https://github.com/aom19/agri-api/blob/main/internal/auth/refresh_service.go"
click node_blacklist "https://github.com/aom19/agri-api/blob/main/internal/auth/blacklist.go"
click node_email "https://github.com/aom19/agri-api/blob/main/internal/email/service.go"
click node_ops "https://github.com/aom19/agri-api/blob/main/internal/usecase/field_operation_service.go"
click node_completion "https://github.com/aom19/agri-api/blob/main/internal/usecase/field_operation_completion_service.go"
click node_crops "https://github.com/aom19/agri-api/blob/main/internal/usecase/crop_service.go"
click node_equipment "https://github.com/aom19/agri-api/blob/main/internal/usecase/assigment_service.go"
click node_reports "https://github.com/aom19/agri-api/blob/main/internal/usecase/report_service.go"
click node_reportdomain "https://github.com/aom19/agri-api/blob/main/internal/domain/report.go"
click node_weather "https://github.com/aom19/agri-api/blob/main/internal/usecase/weather_service.go"
click node_inventory "https://github.com/aom19/agri-api/blob/main/internal/usecase/resource_service.go"
click node_notifications "https://github.com/aom19/agri-api/blob/main/internal/usecase/notification_service.go"
click node_overdue "https://github.com/aom19/agri-api/blob/main/internal/usecase/field_operation_overdue_monitor.go"
click node_snapshots "https://github.com/aom19/agri-api/blob/main/internal/usecase/weather_snapshot_monitor.go"
click node_digest "https://github.com/aom19/agri-api/blob/main/internal/usecase/report_digest_service.go"
click node_store "https://github.com/aom19/agri-api/blob/main/internal/store/store.go"
click node_pgrepos "https://github.com/aom19/agri-api/tree/main/internal/repository/postgres"
click node_postgres "https://github.com/aom19/agri-api/blob/main/internal/db/postgres.go"
click node_redis "https://github.com/aom19/agri-api/blob/main/internal/redis/client.go"

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_entry,node_router,node_handlers,node_middleware,node_client toneBlue
class node_ops,node_completion,node_crops,node_equipment,node_reports,node_reportdomain,node_weather,node_inventory,node_notifications toneAmber
class node_store,node_pgrepos,node_postgres,node_smtp toneMint
class node_authservice,node_jwt,node_refresh,node_blacklist,node_email,node_redis toneRose
class node_overdue,node_snapshots,node_digest,node_meteo toneIndigo
```

## Components

### HTTP API

- [Server startup](https://github.com/aom19/agri-api/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [HTTP routes](https://github.com/aom19/agri-api/blob/main/internal/delivery/http/router.go): `internal/delivery/http/router.go`
- [API handlers](https://github.com/aom19/agri-api/tree/main/internal/delivery/http/handlers): `internal/delivery/http/handlers`
- [Auth middleware](https://github.com/aom19/agri-api/blob/main/internal/delivery/http/middleware/auth.go): `internal/delivery/http/middleware/auth.go`

### Agricultural workflows

- [Field operations](https://github.com/aom19/agri-api/blob/main/internal/usecase/field_operation_service.go): `internal/usecase/field_operation_service.go`
- [Operation completion](https://github.com/aom19/agri-api/blob/main/internal/usecase/field_operation_completion_service.go): `internal/usecase/field_operation_completion_service.go`
- [Crop management](https://github.com/aom19/agri-api/blob/main/internal/usecase/crop_service.go): `internal/usecase/crop_service.go`
- [Farm equipment](https://github.com/aom19/agri-api/blob/main/internal/usecase/assigment_service.go): `internal/usecase/assigment_service.go`
- [Reporting](https://github.com/aom19/agri-api/blob/main/internal/usecase/report_service.go): `internal/usecase/report_service.go`
- [Report models](https://github.com/aom19/agri-api/blob/main/internal/domain/report.go): `internal/domain/report.go`
- [Weather service](https://github.com/aom19/agri-api/blob/main/internal/usecase/weather_service.go): `internal/usecase/weather_service.go`
- [Resources and stock](https://github.com/aom19/agri-api/blob/main/internal/usecase/resource_service.go): `internal/usecase/resource_service.go`
- [Notifications](https://github.com/aom19/agri-api/blob/main/internal/usecase/notification_service.go): `internal/usecase/notification_service.go`

### Persistence

- [Repository store](https://github.com/aom19/agri-api/blob/main/internal/store/store.go): `internal/store/store.go`
- [Postgres repositories](https://github.com/aom19/agri-api/tree/main/internal/repository/postgres): `internal/repository/postgres`
- [PostgreSQL](https://github.com/aom19/agri-api/blob/main/internal/db/postgres.go): `internal/db/postgres.go`

### Identity and messaging

- [Authentication](https://github.com/aom19/agri-api/blob/main/internal/usecase/auth_service.go): `internal/usecase/auth_service.go`
- [JWT service](https://github.com/aom19/agri-api/blob/main/internal/auth/jwt_service.go): `internal/auth/jwt_service.go`
- [Refresh tokens](https://github.com/aom19/agri-api/blob/main/internal/auth/refresh_service.go): `internal/auth/refresh_service.go`
- [Token blacklist](https://github.com/aom19/agri-api/blob/main/internal/auth/blacklist.go): `internal/auth/blacklist.go`
- [Email delivery](https://github.com/aom19/agri-api/blob/main/internal/email/service.go): `internal/email/service.go`
- [Redis](https://github.com/aom19/agri-api/blob/main/internal/redis/client.go): `internal/redis/client.go`

### Background services

- [Overdue monitor](https://github.com/aom19/agri-api/blob/main/internal/usecase/field_operation_overdue_monitor.go): `internal/usecase/field_operation_overdue_monitor.go`
- [Weather snapshots](https://github.com/aom19/agri-api/blob/main/internal/usecase/weather_snapshot_monitor.go): `internal/usecase/weather_snapshot_monitor.go`
- [Report digests](https://github.com/aom19/agri-api/blob/main/internal/usecase/report_digest_service.go): `internal/usecase/report_digest_service.go`

### Other components

- **API client**
- **Open-Meteo**
- **SMTP server**

## Connections

- API client → HTTP routes: sends requests (evidence: `internal/delivery/http/router.go`)
- Server startup → HTTP routes: registers routes
- HTTP routes → API handlers: routes requests (evidence: `internal/delivery/http/router.go`)
- HTTP routes → Auth middleware: protects API (evidence: `internal/delivery/http/router.go`)
- API handlers → Authentication: invokes auth
- API handlers → Field operations: invokes operations
- API handlers → Operation completion: completes work (evidence: `internal/delivery/http/handlers/field_operation_handler.go`)
- API handlers → Crop management: invokes crop logic
- API handlers → Farm equipment: invokes assignments
- API handlers → Reporting: requests reports
- API handlers → Resources and stock: manages stock
- API handlers → Notifications: manages notifications
- Auth middleware → JWT service: validates tokens
- Auth middleware → Token blacklist: checks blacklist
- Authentication → JWT service: issues tokens (evidence: `internal/usecase/auth_service.go`)
- Authentication → Refresh tokens: stores refresh tokens (evidence: `internal/usecase/auth_service.go`)
- Authentication → Token blacklist: revokes tokens (evidence: `internal/usecase/auth_service.go`)
- Authentication → Email delivery: sends account mail (evidence: `internal/usecase/auth_service.go`)
- Field operations → Postgres repositories: persists operations
- Operation completion → Postgres repositories: records completion
- Crop management → Postgres repositories: persists crops
- Farm equipment → Postgres repositories: persists assignments
- Reporting → Postgres repositories: queries reports
- Reporting → Report models: builds report models (evidence: `internal/usecase/report_service.go`)
- Resources and stock → Postgres repositories: persists inventory
- Postgres repositories → PostgreSQL: reads and writes
- Repository store → Postgres repositories: aggregates repositories
- Server startup → Overdue monitor: starts monitor (evidence: `cmd/api/main.go`)
- Server startup → Weather snapshots: starts monitor (evidence: `cmd/api/main.go`)
- Server startup → Report digests: starts digest job (evidence: `cmd/api/main.go`)
- Overdue monitor → Postgres repositories: checks overdue work
- Weather snapshots → Weather service: fetches conditions
- Weather snapshots → Postgres repositories: stores snapshots
- Weather service → Open-Meteo: fetches forecasts
- Report digests → Reporting: generates digests
- Report digests → Email delivery: sends summaries
- Email delivery → SMTP server: sends mail (evidence: `internal/email/service.go`)
- Server startup → PostgreSQL: opens connection
- Server startup → Redis: initializes client