# leafth/maneja-api architecture

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

- Interactive diagram: https://gitdiagram.com/leafth/maneja-api
- Repository: https://github.com/leafth/maneja-api

## Overview

MANEJA API is a Rails/PostgreSQL backend for managing livestock groups, grazing terrain, feed inventory, feeding plans and account access. Its main workflow is authenticated API requests that create or query domain records, with services enforcing operations and serializers shaping JSON responses. Distinct workflows cover occupations and terrain rest, feed movements and requirements, and planning. The README gives no further product detail; unsampled modules are represented only where the tree establishes their subsystem, and edges are limited to relationships visible in excerpts or explicitly documented routes.

Main entry points: [`config/routes.rb`](https://github.com/leafth/maneja-api/blob/main/config/routes.rb) (REST routes), [`app/controllers/api/v1/auth`](https://github.com/leafth/maneja-api/tree/main/app/controllers/api/v1/auth) (Auth endpoints), [`app/controllers/api/v1/base_controller.rb`](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/base_controller.rb) (Request base), [`app/controllers/api/v1/groups_controller.rb`](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/groups_controller.rb) (Group endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_routes["REST routes<br/>[routes.rb]"]
  node_base["Request base<br/>[base_controller.rb]"]
  node_serializers["JSON serializers"]
end

subgraph group_auth["Identity"]
  node_authcontrollers["Auth endpoints"]
  node_authservices["Token and sessions"]
end

subgraph group_grazing["Grazing operations"]
  node_groupsapi["Group endpoints"]
  node_groupsvc["Group operations"]
  node_groupquery["Group listing<br/>[query.rb]"]
  node_terrainapi["Terrain endpoints"]
  node_terrainsvc["Terrain operations"]
  node_terrainquery["Terrain listing<br/>[query.rb]"]
  node_occupationapi["Occupation endpoints"]
  node_occupationsvc["Occupation lifecycle"]
  node_terrainjob["Rest release job"]
end

subgraph group_feed["Feed management"]
  node_feedapi["Feed endpoints"]
  node_feedsvc["Feed operations"]
  node_feedquery["Feed listing<br/>[query.rb]"]
  node_movementapi["Stock movements"]
  node_movementservice["Movement records"]
  node_requirementapi["Feed requirements"]
  node_requirementsvc["Requirement operations"]
  node_feedingapi["Feeding records"]
  node_feedingsvc["Feeding operations"]
  node_planningapi["Planning endpoint"]
  node_planning["Feed planner<br/>[calculate.rb]"]
end

subgraph group_persistence["Domain persistence"]
  node_authmodels["User sessions<br/>[session.rb]"]
  node_database[("PostgreSQL records")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_routes
node_routes -->|"routes auth"| node_authcontrollers
node_routes -->|"routes groups"| node_groupsapi
node_routes -->|"routes terrain"| node_terrainapi
node_routes -->|"routes occupations"| node_occupationapi
node_routes -->|"routes feeds"| node_feedapi
node_routes -->|"routes movements"| node_movementapi
node_routes -->|"routes requirements"| node_requirementapi
node_routes -->|"routes feeding"| node_feedingapi
node_routes -->|"routes planning"| node_planningapi
node_authcontrollers -->|"inherits"| node_base
node_authcontrollers -->|"authenticates"| node_authservices
node_base -->|"decodes token"| node_authservices
node_base -->|"checks session"| node_authmodels
node_authcontrollers -->|"revokes session"| node_authmodels
node_groupsapi -.->|"calls operations"| node_groupsvc
node_groupsapi -.->|"lists records"| node_groupquery
node_terrainapi -.->|"calls operations"| node_terrainsvc
node_terrainapi -.->|"lists records"| node_terrainquery
node_occupationapi -.->|"calls lifecycle"| node_occupationsvc
node_terrainjob -.->|"releases resting"| node_terrainsvc
node_feedapi -.->|"calls operations"| node_feedsvc
node_feedapi -.->|"lists records"| node_feedquery
node_movementapi -->|"creates history"| node_movementservice
node_requirementapi -->|"calls operations"| node_requirementsvc
node_feedingapi -.->|"records feeding"| node_feedingsvc
node_planningapi -.->|"calculates plan"| node_planning
node_serializers -.->|"serializes records"| node_database

click node_routes "https://github.com/leafth/maneja-api/blob/main/config/routes.rb"
click node_base "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/base_controller.rb"
click node_serializers "https://github.com/leafth/maneja-api/tree/main/app/serializers"
click node_authcontrollers "https://github.com/leafth/maneja-api/tree/main/app/controllers/api/v1/auth"
click node_authservices "https://github.com/leafth/maneja-api/tree/main/app/services/auth"
click node_authmodels "https://github.com/leafth/maneja-api/blob/main/app/models/session.rb"
click node_groupsapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/groups_controller.rb"
click node_groupsvc "https://github.com/leafth/maneja-api/tree/main/app/services/groups"
click node_groupquery "https://github.com/leafth/maneja-api/blob/main/app/queries/groups/query.rb"
click node_terrainapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/terrains_controller.rb"
click node_terrainsvc "https://github.com/leafth/maneja-api/tree/main/app/services/terrains"
click node_terrainquery "https://github.com/leafth/maneja-api/blob/main/app/queries/terrains/query.rb"
click node_occupationapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/occupations_controller.rb"
click node_occupationsvc "https://github.com/leafth/maneja-api/tree/main/app/services/occupations"
click node_terrainjob "https://github.com/leafth/maneja-api/blob/main/app/jobs/terrains/release_resting_job.rb"
click node_feedapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feeds_controller.rb"
click node_feedsvc "https://github.com/leafth/maneja-api/tree/main/app/services/feeds"
click node_feedquery "https://github.com/leafth/maneja-api/blob/main/app/queries/feeds/query.rb"
click node_movementapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feed_movements_controller.rb"
click node_movementservice "https://github.com/leafth/maneja-api/tree/main/app/services/feed_movements"
click node_requirementapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feed_requirements_controller.rb"
click node_requirementsvc "https://github.com/leafth/maneja-api/tree/main/app/services/feed_requirements"
click node_feedingapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feedings_controller.rb"
click node_feedingsvc "https://github.com/leafth/maneja-api/tree/main/app/services/feedings"
click node_planningapi "https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feed_planning_controller.rb"
click node_planning "https://github.com/leafth/maneja-api/blob/main/app/services/feed_planning/calculate.rb"
click node_database "https://github.com/leafth/maneja-api/blob/main/app/models/application_record.rb"

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_routes,node_base,node_serializers,node_client toneBlue
class node_authcontrollers,node_authservices toneAmber
class node_groupsapi,node_groupsvc,node_groupquery,node_terrainapi,node_terrainsvc,node_terrainquery,node_occupationapi,node_occupationsvc,node_terrainjob toneMint
class node_feedapi,node_feedsvc,node_feedquery,node_movementapi,node_movementservice,node_requirementapi,node_requirementsvc,node_feedingapi,node_feedingsvc,node_planningapi,node_planning toneRose
class node_authmodels,node_database toneIndigo
```

## Components

### API boundary

- [REST routes](https://github.com/leafth/maneja-api/blob/main/config/routes.rb): `config/routes.rb`
- [Request base](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/base_controller.rb): `app/controllers/api/v1/base_controller.rb`
- [JSON serializers](https://github.com/leafth/maneja-api/tree/main/app/serializers): `app/serializers`

### Identity

- [Auth endpoints](https://github.com/leafth/maneja-api/tree/main/app/controllers/api/v1/auth): `app/controllers/api/v1/auth`
- [Token and sessions](https://github.com/leafth/maneja-api/tree/main/app/services/auth): `app/services/auth`

### Grazing operations

- [Group endpoints](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/groups_controller.rb): `app/controllers/api/v1/groups_controller.rb`
- [Group operations](https://github.com/leafth/maneja-api/tree/main/app/services/groups): `app/services/groups`
- [Group listing](https://github.com/leafth/maneja-api/blob/main/app/queries/groups/query.rb): `app/queries/groups/query.rb`
- [Terrain endpoints](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/terrains_controller.rb): `app/controllers/api/v1/terrains_controller.rb`
- [Terrain operations](https://github.com/leafth/maneja-api/tree/main/app/services/terrains): `app/services/terrains`
- [Terrain listing](https://github.com/leafth/maneja-api/blob/main/app/queries/terrains/query.rb): `app/queries/terrains/query.rb`
- [Occupation endpoints](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/occupations_controller.rb): `app/controllers/api/v1/occupations_controller.rb`
- [Occupation lifecycle](https://github.com/leafth/maneja-api/tree/main/app/services/occupations): `app/services/occupations`
- [Rest release job](https://github.com/leafth/maneja-api/blob/main/app/jobs/terrains/release_resting_job.rb): `app/jobs/terrains/release_resting_job.rb`

### Feed management

- [Feed endpoints](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feeds_controller.rb): `app/controllers/api/v1/feeds_controller.rb`
- [Feed operations](https://github.com/leafth/maneja-api/tree/main/app/services/feeds): `app/services/feeds`
- [Feed listing](https://github.com/leafth/maneja-api/blob/main/app/queries/feeds/query.rb): `app/queries/feeds/query.rb`
- [Stock movements](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feed_movements_controller.rb): `app/controllers/api/v1/feed_movements_controller.rb`
- [Movement records](https://github.com/leafth/maneja-api/tree/main/app/services/feed_movements): `app/services/feed_movements`
- [Feed requirements](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feed_requirements_controller.rb): `app/controllers/api/v1/feed_requirements_controller.rb`
- [Requirement operations](https://github.com/leafth/maneja-api/tree/main/app/services/feed_requirements): `app/services/feed_requirements`
- [Feeding records](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feedings_controller.rb): `app/controllers/api/v1/feedings_controller.rb`
- [Feeding operations](https://github.com/leafth/maneja-api/tree/main/app/services/feedings): `app/services/feedings`
- [Planning endpoint](https://github.com/leafth/maneja-api/blob/main/app/controllers/api/v1/feed_planning_controller.rb): `app/controllers/api/v1/feed_planning_controller.rb`
- [Feed planner](https://github.com/leafth/maneja-api/blob/main/app/services/feed_planning/calculate.rb): `app/services/feed_planning/calculate.rb`

### Domain persistence

- [User sessions](https://github.com/leafth/maneja-api/blob/main/app/models/session.rb): `app/models/session.rb`
- [PostgreSQL records](https://github.com/leafth/maneja-api/blob/main/app/models/application_record.rb): `app/models/application_record.rb`

### Other components

- **API client**

## Connections

- API client → REST routes: sends requests (evidence: `config/routes.rb`)
- REST routes → Auth endpoints: routes auth (evidence: `config/routes.rb`)
- REST routes → Group endpoints: routes groups (evidence: `config/routes.rb`)
- REST routes → Terrain endpoints: routes terrain (evidence: `config/routes.rb`)
- REST routes → Occupation endpoints: routes occupations (evidence: `config/routes.rb`)
- REST routes → Feed endpoints: routes feeds (evidence: `config/routes.rb`)
- REST routes → Stock movements: routes movements (evidence: `config/routes.rb`)
- REST routes → Feed requirements: routes requirements (evidence: `config/routes.rb`)
- REST routes → Feeding records: routes feeding (evidence: `config/routes.rb`)
- REST routes → Planning endpoint: routes planning (evidence: `config/routes.rb`)
- Auth endpoints → Request base: inherits (evidence: `app/controllers/api/v1/auth/sessions_controller.rb`)
- Auth endpoints → Token and sessions: authenticates (evidence: `app/controllers/api/v1/auth/sessions_controller.rb`)
- Request base → Token and sessions: decodes token (evidence: `app/controllers/api/v1/base_controller.rb`)
- Request base → User sessions: checks session (evidence: `app/controllers/api/v1/base_controller.rb`)
- Auth endpoints → User sessions: revokes session (evidence: `app/controllers/api/v1/auth/sessions_controller.rb`)
- Group endpoints → Group operations: calls operations
- Group endpoints → Group listing: lists records
- Terrain endpoints → Terrain operations: calls operations
- Terrain endpoints → Terrain listing: lists records
- Occupation endpoints → Occupation lifecycle: calls lifecycle
- Rest release job → Terrain operations: releases resting
- Feed endpoints → Feed operations: calls operations
- Feed endpoints → Feed listing: lists records
- Stock movements → Movement records: creates history (evidence: `app/controllers/api/v1/feed_movements_controller.rb`)
- Feed requirements → Requirement operations: calls operations (evidence: `app/controllers/api/v1/feed_requirements_controller.rb`)
- Feeding records → Feeding operations: records feeding
- Planning endpoint → Feed planner: calculates plan
- JSON serializers → PostgreSQL records: serializes records