# itimkacommunity/smart-agro-quest architecture

> Architecture diagram of the GitHub repository itimkacommunity/smart-agro-quest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itimkacommunity/smart-agro-quest
- Repository: https://github.com/itimkacommunity/smart-agro-quest

## Overview

1. **Overall shape**
   - This is a **two-tier application**: a **React/Vite SPA frontend** and a **NestJS backend**.
   - The backend is organized as a **modular monolith**: business areas are separated into Nest modules, but they run in one server process and share the same PostgreSQL database.

2. **Client layer**
   - The frontend lives in `src/` and is the primary user-facing surface.
   - It uses **React Router** for page navigation, **TanStack Query** for server state, and a centralized API client in `src/lib/api-client.ts`.
   - The UI is split by domain: auth, farm, pet, tasks, achievements, analytics, teacher tools, and shared layout/system components.

3. **Backend application boundary**
   - The backend lives in `backend/src/` and exposes **REST APIs** plus **Socket.IO real-time channels**.
   - Each domain module owns its controller, service, DTOs, entities, and in some cases a WebSocket gateway.
   - Cross-cutting concerns are centralized in `backend/src/common/` for guards, filters, interceptors, and decorators.

4. **Core domain modules**
   - The main business modules are: **auth, users, tasks, farm, pet, achievements, progress, zones, groups, storage, monitoring, health**.
   - `tasks`, `farm`, and `pet` are the most interactive domains and drive most user engagement.
   - `users`, `progress`, `achievements`, `zones`, and `groups` support the educational and gamification model around those core activities.

5. **Authentication and authorization flow**
   - Authentication uses **Passport + JWT** with local and JWT strategies.
   - Route protection is enforced by JWT guards and role-based guards/decorators, with roles such as **student, teacher, admin**.
   - The frontend consumes the auth endpoints and stores session state in the app context/hooks rather than talking directly to the database.

6. **Primary data store**
   - The system persists its business data in **PostgreSQL** through **TypeORM**.
   - The database schema covers profiles, tasks/submissions/comments, farm entities and inventories, pets/shop items, achievements, zone progress, groups, booster state, and teacher subjects.
   - Migrations and seed scripts are part of the backend repository, which makes the database schema an explicit application boundary rather than an external managed model.

7. **Real-time subsystem**
   - Real-time updates are handled with **Socket.IO** in dedicated gateways for **farm**, **pet**, and **tasks**.
   - The frontend connects through websocket hooks/managers and listens for state changes such as plant updates, harvests, pet actions, production completion, and task-related events.
   - Redis is used as the **Socket.IO adapter/pub-sub layer**, allowing horizontal scaling and message propagation across instances.

8. **File and media storage**
   - There is a dedicated **storage module** for file uploads and retrieval.
   - The repo supports local filesystem storage and is designed to work with **S3-compatible storage** such as MinIO in deployment.
   - This is a separate boundary from the main transactional database: structured app state stays in PostgreSQL, binary assets go to the storage subsystem.

9. **Monitoring and health**
   - `monitoring` and `health` are backend modules that expose operational visibility.
   - Prometheus-style metrics are integrated via interceptors and a dedicated monitoring service, while health checks provide basic service liveness/readiness.
   - The repo also includes ready-made config for **Prometheus, Grafana, Loki, Promtail, and ELK**, indicating an observability stack outside the core app runtime.

10. **Deployment and runtime topology**
   - The project is packaged for **Docker Compose** in development/staging and has **Kubernetes manifests** for production.
   - An **Nginx reverse proxy** sits in front of the app in the documented architecture, handling routing, SSL, and load balancing.
   - Separate compose files and configs exist for monitoring, ELK logging, and PostgreSQL HA, so infrastructure is treated as a first-class part of the architecture.

11. **Testing and quality gates**
   - The backend has unit and E2E tests under `backend/test/`.
   - The repo also has **Playwright E2E** and **visual regression** suites at the root level.
   - GitHub Actions workflows run CI/CD and visual checks, so test coverage spans backend behavior, browser flows, and UI stability.

12. **Platform dependencies and external services**
   - The core product does **not depend on Supabase for its business logic**, though leftover Supabase client files and edge functions exist.
   - Those Supabase functions are limited to auxiliary jobs such as weekly reports and overdue reminders, and could be replaced by backend scheduled jobs.
   - There is a planned but not yet integrated **AI copilot** boundary, with frontend UI in place and a future FastAPI service expected behind it.

Main entry points: [`backend/src/app.module.ts`](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/app.module.ts) (App Module), [`backend/database/schema.sql`](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/database/schema.sql) (PostgreSQL), [`src/lib/api-client.ts`](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/lib/api-client.ts) (API Client), [`src/main.tsx`](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/main.tsx) (SPA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_spa["SPA<br/>React/Vite app<br/>[main.tsx]"]
  node_router["Pages<br/>routes<br/>[Index.tsx]"]
  node_api_client["API Client<br/>http client<br/>[api-client.ts]"]
  node_auth_ui["Auth UI<br/>session flow<br/>[AuthContext.tsx]"]
  node_realtime_ui["Realtime Hooks<br/>ws client"]
  node_feature_ui["Domain UI<br/>feature components<br/>[FarmZoneView.tsx]"]
end

subgraph group_backend["Backend"]
  node_nest_app["App Module<br/>Nest bootstrap<br/>[app.module.ts]"]
  node_common["Common<br/>cross-cutting<br/>[jwt-auth.guard.ts]"]
  node_auth_mod["Auth<br/>security module<br/>[auth.module.ts]"]
  node_user_mod["Users<br/>profile module<br/>[users.module.ts]"]
  node_task_mod["Tasks<br/>workflow module<br/>[tasks.module.ts]"]
  node_farm_mod["Farm<br/>gameplay module<br/>[farm.module.ts]"]
  node_pet_mod["Pet<br/>gameplay module<br/>[pet.module.ts]"]
  node_game_support["Gamification<br/>support modules"]
  node_storage_mod["Storage<br/>asset module<br/>[storage.module.ts]"]
  node_ops_mod["Ops APIs<br/>ops module"]
end

subgraph group_infra["Runtime & Ops"]
  node_db[("PostgreSQL<br/>TypeORM store<br/>[schema.sql]")]
  node_redis[("Redis<br/>socket adapter")]
  node_proxy["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_deploy["Deploy<br/>compose/k8s<br/>[docker-compose.yml]"]
  node_obs["Observability<br/>metrics/logging<br/>[prometheus.yml]"]
end

subgraph group_quality["Quality"]
  node_ci["CI/CD<br/>workflows<br/>[ci-cd.yml]"]
  node_e2e["E2E Tests<br/>browser/backend tests<br/>[auth.spec.ts]"]
end

node_spa -->|"renders"| node_router
node_spa -->|"uses"| node_auth_ui
node_spa -->|"calls"| node_api_client
node_spa -->|"subscribes"| node_realtime_ui
node_spa -->|"hosts"| node_feature_ui
node_api_client -->|"REST"| node_auth_mod
node_api_client -->|"REST"| node_task_mod
node_api_client -->|"REST"| node_farm_mod
node_api_client -->|"REST"| node_pet_mod
node_api_client -->|"REST"| node_game_support
node_realtime_ui -->|"ws"| node_farm_mod
node_realtime_ui -->|"ws"| node_pet_mod
node_realtime_ui -->|"ws"| node_task_mod
node_nest_app -->|"imports"| node_common
node_nest_app -->|"loads"| node_auth_mod
node_nest_app -->|"loads"| node_user_mod
node_nest_app -->|"loads"| node_task_mod
node_nest_app -->|"loads"| node_farm_mod
node_nest_app -->|"loads"| node_pet_mod
node_nest_app -->|"loads"| node_game_support
node_nest_app -->|"loads"| node_storage_mod
node_nest_app -->|"loads"| node_ops_mod
node_auth_mod -->|"reads/writes"| node_db
node_user_mod -->|"reads/writes"| node_db
node_task_mod -->|"reads/writes"| node_db
node_farm_mod -->|"reads/writes"| node_db
node_pet_mod -->|"reads/writes"| node_db
node_game_support -->|"reads/writes"| node_db
node_storage_mod -->|"metadata"| node_db
node_farm_mod -->|"pub/sub"| node_redis
node_pet_mod -->|"pub/sub"| node_redis
node_task_mod -->|"pub/sub"| node_redis
node_deploy -->|"fronts"| node_proxy
node_deploy -->|"includes"| node_obs
node_deploy -->|"runs with"| node_db
node_obs -->|"observes"| node_ops_mod
node_ci -->|"runs"| node_e2e
node_ci -->|"validates"| node_deploy

click node_spa "https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/main.tsx"
click node_router "https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/pages/Index.tsx"
click node_api_client "https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/lib/api-client.ts"
click node_auth_ui "https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/contexts/AuthContext.tsx"
click node_realtime_ui "https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/hooks/websocketManager.ts"
click node_feature_ui "https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/components/farm/FarmZoneView.tsx"
click node_nest_app "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/app.module.ts"
click node_common "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/common/guards/jwt-auth.guard.ts"
click node_auth_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/auth/auth.module.ts"
click node_user_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/users/users.module.ts"
click node_task_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/tasks/tasks.module.ts"
click node_farm_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/farm/farm.module.ts"
click node_pet_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/pet/pet.module.ts"
click node_game_support "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/achievements/achievements.module.ts"
click node_storage_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/storage/storage.module.ts"
click node_ops_mod "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/monitoring/monitoring.module.ts"
click node_db "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/database/schema.sql"
click node_redis "https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/adapters/redis-io.adapter.ts"
click node_proxy "https://github.com/itimkacommunity/smart-agro-quest/blob/main/nginx.conf"
click node_deploy "https://github.com/itimkacommunity/smart-agro-quest/blob/main/docker-compose.yml"
click node_obs "https://github.com/itimkacommunity/smart-agro-quest/blob/main/monitoring/prometheus/prometheus.yml"
click node_ci "https://github.com/itimkacommunity/smart-agro-quest/blob/main/.github/workflows/ci-cd.yml"
click node_e2e "https://github.com/itimkacommunity/smart-agro-quest/blob/main/e2e/auth.spec.ts"

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_spa,node_router,node_api_client,node_auth_ui,node_realtime_ui,node_feature_ui toneBlue
class node_nest_app,node_common,node_auth_mod,node_user_mod,node_task_mod,node_farm_mod,node_pet_mod,node_game_support,node_storage_mod,node_ops_mod toneAmber
class node_db,node_redis,node_proxy,node_deploy,node_obs toneMint
class node_ci,node_e2e toneRose
```

## Components

### Frontend

React/Vite SPA and browser-side state, routing, and realtime hooks.

- [SPA](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/main.tsx): React/Vite app · Main browser application and page shell. · `src/main.tsx`
- [Pages](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/pages/Index.tsx): routes · Page-level navigation and feature entry points. · `src/pages/Index.tsx`
- [API Client](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/lib/api-client.ts): http client · Centralized frontend API access layer. · `src/lib/api-client.ts`
- [Auth UI](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/contexts/AuthContext.tsx): session flow · Login/session context and protected routes. · `src/contexts/AuthContext.tsx`
- [Realtime Hooks](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/hooks/websocketManager.ts): ws client · WebSocket managers and domain-specific live updates. · `src/hooks/websocketManager.ts`
- [Domain UI](https://github.com/itimkacommunity/smart-agro-quest/blob/main/src/components/farm/FarmZoneView.tsx): feature components · Farm, pet, tasks, achievements, analytics, and teacher tools. · `src/components/farm/FarmZoneView.tsx`

### Backend

NestJS modular monolith with REST, WebSocket, and PostgreSQL access.

- [App Module](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/app.module.ts): Nest bootstrap · Backend composition root and runtime wiring. · `backend/src/app.module.ts`
- [Common](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/common/guards/jwt-auth.guard.ts): cross-cutting · Guards, decorators, filters, interceptors, and middleware. · `backend/src/common/guards/jwt-auth.guard.ts`
- [Auth](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/auth/auth.module.ts): security module · Passport local/JWT authentication and authorization. · `backend/src/modules/auth/auth.module.ts`
- [Users](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/users/users.module.ts): profile module · User profiles, teacher subjects, and user-facing account data. · `backend/src/modules/users/users.module.ts`
- [Tasks](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/tasks/tasks.module.ts): workflow module · Assignments, submissions, comments, grading, and analytics. · `backend/src/modules/tasks/tasks.module.ts`
- [Farm](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/farm/farm.module.ts): gameplay module · Plants, production, inventory, boosters, and farm activity. · `backend/src/modules/farm/farm.module.ts`
- [Pet](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/pet/pet.module.ts): gameplay module · Pets, items, and pet interactions. · `backend/src/modules/pet/pet.module.ts`
- [Gamification](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/achievements/achievements.module.ts): support modules · Achievements, progress, zones, and groups supporting game/learning flow. · `backend/src/modules/achievements/achievements.module.ts`
- [Storage](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/storage/storage.module.ts): asset module · File upload and retrieval boundary for binary assets. · `backend/src/modules/storage/storage.module.ts`
- [Ops APIs](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/modules/monitoring/monitoring.module.ts): ops module · Monitoring and health endpoints. · `backend/src/modules/monitoring/monitoring.module.ts`

### Runtime & Ops

Deployment, proxying, storage, observability, and database infrastructure.

- [PostgreSQL](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/database/schema.sql): TypeORM store · Primary transactional database and schema boundary. · `backend/database/schema.sql`
- [Redis](https://github.com/itimkacommunity/smart-agro-quest/blob/main/backend/src/adapters/redis-io.adapter.ts): socket adapter · Socket.IO adapter and pub/sub layer for realtime fanout. · `backend/src/adapters/redis-io.adapter.ts`
- [Nginx](https://github.com/itimkacommunity/smart-agro-quest/blob/main/nginx.conf): reverse proxy · Front door for routing, SSL, and load balancing. · `nginx.conf`
- [Deploy](https://github.com/itimkacommunity/smart-agro-quest/blob/main/docker-compose.yml): compose/k8s · Docker Compose and Kubernetes runtime definitions. · `docker-compose.yml`
- [Observability](https://github.com/itimkacommunity/smart-agro-quest/blob/main/monitoring/prometheus/prometheus.yml): metrics/logging · Prometheus, Grafana, Loki, and ELK configuration. · `monitoring/prometheus/prometheus.yml`

### Quality

Automated tests and CI/CD workflows.

- [CI/CD](https://github.com/itimkacommunity/smart-agro-quest/blob/main/.github/workflows/ci-cd.yml): workflows · GitHub Actions for tests, builds, and visual checks. · `.github/workflows/ci-cd.yml`
- [E2E Tests](https://github.com/itimkacommunity/smart-agro-quest/blob/main/e2e/auth.spec.ts): browser/backend tests · Playwright and backend end-to-end verification. · `e2e/auth.spec.ts`

## Connections

- SPA → Pages: renders · The SPA mounts page routing and feature shells.
- SPA → Auth UI: uses · Client session state and route protection are handled in the frontend.
- SPA → API Client: calls · Frontend talks to backend through a centralized HTTP client.
- SPA → Realtime Hooks: subscribes · Browser hooks consume Socket.IO updates for live gameplay.
- SPA → Domain UI: hosts · Feature components implement the main user-facing domains.
- API Client → Auth: REST · Frontend auth flows consume backend authentication endpoints.
- API Client → Tasks: REST · Tasks, submissions, and teacher tooling use REST APIs.
- API Client → Farm: REST · Farm actions and state are served over HTTP.
- API Client → Pet: REST · Pet interactions and inventory flows use HTTP APIs.
- API Client → Gamification: REST · Achievements, progress, zones, and groups are fetched via APIs.
- Realtime Hooks → Farm: ws · Farm live updates arrive through dedicated gateways.
- Realtime Hooks → Pet: ws · Pet live updates arrive through dedicated gateways.
- Realtime Hooks → Tasks: ws · Task-related live events are pushed in realtime.
- App Module → Common: imports · Shared guards, interceptors, decorators, and middleware are wired globally.
- App Module → Auth: loads · Authentication is a core backend module.
- App Module → Users: loads · User and profile data are part of the monolith.
- App Module → Tasks: loads · Task management is a major backend subsystem.
- App Module → Farm: loads · Farm gameplay is a core backend subsystem.
- App Module → Pet: loads · Pet gameplay is a core backend subsystem.
- App Module → Gamification: loads · Achievements, progress, zones, and groups support the main gameplay loop.
- App Module → Storage: loads · Storage is a separate backend boundary for files and media.
- App Module → Ops APIs: loads · Monitoring and health endpoints are exposed by the backend.
- Auth → PostgreSQL: reads/writes · Authentication persists users and session-related domain state in PostgreSQL.
- Users → PostgreSQL: reads/writes · Profiles and teacher subject data are stored in PostgreSQL.
- Tasks → PostgreSQL: reads/writes · Tasks, submissions, comments, and analytics data live in PostgreSQL.
- Farm → PostgreSQL: reads/writes · Farm entities, inventories, and production state persist in PostgreSQL.
- Pet → PostgreSQL: reads/writes · Pet state and shop/item relationships persist in PostgreSQL.
- Gamification → PostgreSQL: reads/writes · Achievements, progress, zones, and groups share the same database.
- Storage → PostgreSQL: metadata · File records are coordinated with transactional app state.
- Farm → Redis: pub/sub · Farm gateways use Redis for Socket.IO scaling.
- Pet → Redis: pub/sub · Pet gateways use Redis for Socket.IO scaling.
- Tasks → Redis: pub/sub · Task gateways use Redis for Socket.IO scaling.
- Deploy → Nginx: fronts · Deployment places Nginx in front of the application stack.
- Deploy → Observability: includes · Runtime composition includes the observability stack.
- Deploy → PostgreSQL: runs with · Database and app services are orchestrated together in deployment.
- Observability → Ops APIs: observes · Backend metrics and health feed the monitoring stack.
- CI/CD → E2E Tests: runs · CI executes browser and backend end-to-end checks.
- CI/CD → Deploy: validates · Workflows cover build and deployment readiness.
