# diazperillaj/shaya architecture

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

- Interactive diagram: https://gitdiagram.com/diazperillaj/shaya
- Repository: https://github.com/diazperillaj/shaya

## Overview

Shaya is a coffee-business management system with a React web app, a FastAPI business API, and a separate analytical-chat service. Staff manage farmer purchases of parchment coffee, processing and roasting, inventory, sales, and fairs; farm users have a distinct cultivation workflow covering farm records, harvest, postharvest, traceability, and quality projections. The chatbot analyzes business data and streams assistant responses. The graph reflects documented routes, service calls, and data access where shown; several farm and frontend subsystem links are necessarily broad because their implementation was not excerpted.

Main entry points: [`backend/app/farm_operations/api/v1/router.py`](https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/router.py) (Farm operations API), [`chatbot/app/services/chat_service.py`](https://github.com/diazperillaj/shaya/blob/main/chatbot/app/services/chat_service.py) (Turn orchestration), [`frontend/src/App.tsx`](https://github.com/diazperillaj/shaya/blob/main/frontend/src/App.tsx) (Web app routing), [`backend/app/core/db/base.py`](https://github.com/diazperillaj/shaya/blob/main/backend/app/core/db/base.py) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web app routing<br/>[App.tsx]"]
  node_webchat["Chat interface<br/>[useChat.ts]"]
end

subgraph group_business["Coffee business API"]
  node_api["Business API<br/>[api_v1.py]"]
  node_parchment["Parchment inventory<br/>[service.py]"]
  node_processing["Maquila and costing<br/>[service.py]"]
  node_roasted["Roasted inventory<br/>[service.py]"]
  node_movement["Inventory movements<br/>[service.py]"]
  node_sales["Sales<br/>[service.py]"]
  node_fairs["Fair sales<br/>[service.py]"]
  node_dashboard["Business dashboard<br/>[service.py]"]
end

subgraph group_farm["Farm operations"]
  node_farmapi["Farm operations API<br/>[router.py]"]
  node_farmrecords["Farm records<br/>[service.py]"]
  node_harvest["Harvest and labor<br/>[service.py]"]
  node_postharvest["Postharvest traceability<br/>[service.py]"]
  node_quality["Quality projection<br/>[service.py]"]
end

subgraph group_assistant["Analytical assistant"]
  node_chatapi["Chat endpoint<br/>[router.py]"]
  node_chatservice["Turn orchestration<br/>[chat_service.py]"]
  node_agent["Agent and tools<br/>[loop.py]"]
  node_memory["Conversation memory<br/>[memory_service.py]"]
end

subgraph group_data["Persistence"]
  node_postgres[("PostgreSQL<br/>[base.py]")]
end

node_user(("Staff or farm user"))
node_llm{{"LLM provider"}}
node_redis[("Redis")]

node_user -->|"uses"| node_webapp
node_webapp -.->|"calls business API"| node_api
node_webapp -.->|"uses farm routes"| node_farmapi
node_webapp -.->|"routes to chat"| node_webchat
node_api -.->|"dispatches"| node_parchment
node_parchment -->|"recalculates costs"| node_processing
node_processing -->|"creates roasted stock"| node_roasted
node_processing -.->|"records stock movement"| node_movement
node_sales -->|"reads and writes"| node_postgres
node_fairs -->|"reads and writes"| node_postgres
node_dashboard -->|"queries business data"| node_postgres
node_farmapi -.->|"dispatches"| node_farmrecords
node_farmapi -.->|"dispatches"| node_harvest
node_farmapi -.->|"dispatches"| node_postharvest
node_farmapi -.->|"dispatches"| node_quality
node_postharvest -.->|"links drying output"| node_parchment
node_webchat -.->|"streams chat"| node_chatapi
node_chatapi -->|"delegates turn"| node_chatservice
node_chatservice -->|"runs agent loop"| node_agent
node_chatservice -->|"loads and appends memory"| node_memory
node_chatservice -->|"requests completions"| node_llm
node_memory -.->|"uses cache"| node_redis
node_chatservice -->|"persists conversation"| node_postgres

click node_webapp "https://github.com/diazperillaj/shaya/blob/main/frontend/src/App.tsx"
click node_webchat "https://github.com/diazperillaj/shaya/blob/main/frontend/src/features/chat/hooks/useChat.ts"
click node_api "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/api_v1.py"
click node_parchment "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/inventory/service.py"
click node_processing "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/processes/service.py"
click node_roasted "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/roasted_coffee/service.py"
click node_movement "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/roasted_movements/service.py"
click node_sales "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/sales/service.py"
click node_fairs "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/fairs/service.py"
click node_dashboard "https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/dashboard/service.py"
click node_farmapi "https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/router.py"
click node_farmrecords "https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/farms/service.py"
click node_harvest "https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/harvests/service.py"
click node_postharvest "https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/traceability/service.py"
click node_quality "https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/quality_projection/service.py"
click node_chatapi "https://github.com/diazperillaj/shaya/blob/main/chatbot/app/api/v1/chat/router.py"
click node_chatservice "https://github.com/diazperillaj/shaya/blob/main/chatbot/app/services/chat_service.py"
click node_agent "https://github.com/diazperillaj/shaya/blob/main/chatbot/app/agent/loop.py"
click node_memory "https://github.com/diazperillaj/shaya/blob/main/chatbot/app/services/memory_service.py"
click node_postgres "https://github.com/diazperillaj/shaya/blob/main/backend/app/core/db/base.py"

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_webapp,node_webchat,node_user toneBlue
class node_api,node_parchment,node_processing,node_roasted,node_movement,node_sales,node_fairs,node_dashboard,node_redis toneAmber
class node_farmapi,node_farmrecords,node_harvest,node_postharvest,node_quality toneMint
class node_chatapi,node_chatservice,node_agent,node_memory toneRose
class node_postgres,node_llm toneIndigo
```

## Components

### Web application

- [Web app routing](https://github.com/diazperillaj/shaya/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat interface](https://github.com/diazperillaj/shaya/blob/main/frontend/src/features/chat/hooks/useChat.ts): `frontend/src/features/chat/hooks/useChat.ts`

### Coffee business API

- [Business API](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/api_v1.py): `backend/app/api/api_v1/api_v1.py`
- [Parchment inventory](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/inventory/service.py): `backend/app/api/api_v1/inventory/service.py`
- [Maquila and costing](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/processes/service.py): `backend/app/api/api_v1/processes/service.py`
- [Roasted inventory](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/roasted_coffee/service.py): `backend/app/api/api_v1/roasted_coffee/service.py`
- [Inventory movements](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/roasted_movements/service.py): `backend/app/api/api_v1/roasted_movements/service.py`
- [Sales](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/sales/service.py): `backend/app/api/api_v1/sales/service.py`
- [Fair sales](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/fairs/service.py): `backend/app/api/api_v1/fairs/service.py`
- [Business dashboard](https://github.com/diazperillaj/shaya/blob/main/backend/app/api/api_v1/dashboard/service.py): `backend/app/api/api_v1/dashboard/service.py`

### Farm operations

- [Farm operations API](https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/router.py): `backend/app/farm_operations/api/v1/router.py`
- [Farm records](https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/farms/service.py): `backend/app/farm_operations/api/v1/farms/service.py`
- [Harvest and labor](https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/harvests/service.py): `backend/app/farm_operations/api/v1/harvests/service.py`
- [Postharvest traceability](https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/traceability/service.py): `backend/app/farm_operations/api/v1/traceability/service.py`
- [Quality projection](https://github.com/diazperillaj/shaya/blob/main/backend/app/farm_operations/api/v1/quality_projection/service.py): `backend/app/farm_operations/api/v1/quality_projection/service.py`

### Analytical assistant

- [Chat endpoint](https://github.com/diazperillaj/shaya/blob/main/chatbot/app/api/v1/chat/router.py): `chatbot/app/api/v1/chat/router.py`
- [Turn orchestration](https://github.com/diazperillaj/shaya/blob/main/chatbot/app/services/chat_service.py): `chatbot/app/services/chat_service.py`
- [Agent and tools](https://github.com/diazperillaj/shaya/blob/main/chatbot/app/agent/loop.py): `chatbot/app/agent/loop.py`
- [Conversation memory](https://github.com/diazperillaj/shaya/blob/main/chatbot/app/services/memory_service.py): `chatbot/app/services/memory_service.py`

### Persistence

- [PostgreSQL](https://github.com/diazperillaj/shaya/blob/main/backend/app/core/db/base.py): `backend/app/core/db/base.py`

### Other components

- **Staff or farm user**
- **LLM provider**
- **Redis**

## Connections

- Staff or farm user → Web app routing: uses (evidence: `README.md`)
- Web app routing → Business API: calls business API (evidence: `README.md`)
- Web app routing → Farm operations API: uses farm routes (evidence: `frontend/src/App.tsx`)
- Web app routing → Chat interface: routes to chat (evidence: `frontend/src/App.tsx`)
- Business API → Parchment inventory: dispatches
- Parchment inventory → Maquila and costing: recalculates costs (evidence: `backend/app/api/api_v1/inventory/service.py`)
- Maquila and costing → Roasted inventory: creates roasted stock (evidence: `backend/app/api/api_v1/processes/service.py`)
- Maquila and costing → Inventory movements: records stock movement (evidence: `backend/app/api/api_v1/processes/service.py`)
- Sales → PostgreSQL: reads and writes (evidence: `backend/app/api/api_v1/sales/service.py`)
- Fair sales → PostgreSQL: reads and writes (evidence: `backend/app/api/api_v1/fairs/service.py`)
- Business dashboard → PostgreSQL: queries business data (evidence: `backend/app/api/api_v1/dashboard/service.py`)
- Farm operations API → Farm records: dispatches
- Farm operations API → Harvest and labor: dispatches
- Farm operations API → Postharvest traceability: dispatches
- Farm operations API → Quality projection: dispatches
- Postharvest traceability → Parchment inventory: links drying output
- Chat interface → Chat endpoint: streams chat (evidence: `README.md`)
- Chat endpoint → Turn orchestration: delegates turn (evidence: `chatbot/app/api/v1/chat/router.py`)
- Turn orchestration → Agent and tools: runs agent loop (evidence: `chatbot/app/services/chat_service.py`)
- Turn orchestration → Conversation memory: loads and appends memory (evidence: `chatbot/app/services/chat_service.py`)
- Turn orchestration → LLM provider: requests completions (evidence: `chatbot/app/services/chat_service.py`)
- Conversation memory → Redis: uses cache (evidence: `chatbot/app/services/memory_service.py`)
- Turn orchestration → PostgreSQL: persists conversation (evidence: `chatbot/app/services/chat_service.py`)
