How itimkacommunity/smart-agro-quest works
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: app.module.ts App Module · schema.sql PostgreSQL · api-client.ts API Client · main.tsx SPA
Components 23
Frontend
React/Vite SPA and browser-side state, routing, and realtime hooks.
- SPA · Main browser application and page shell.
src/main.tsx - Pages · Page-level navigation and feature entry points.
src/pages/Index.tsx - API Client · Centralized frontend API access layer.
src/lib/api-client.ts - Auth UI · Login/session context and protected routes.
src/contexts/AuthContext.tsx - Realtime Hooks · WebSocket managers and domain-specific live updates.
src/hooks/websocketManager.ts - Domain UI · 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 · Backend composition root and runtime wiring.
backend/src/app.module.ts - Common · Guards, decorators, filters, interceptors, and middleware.
backend/src/common/guards/jwt-auth.guard.ts - Auth · Passport local/JWT authentication and authorization.
backend/src/modules/auth/auth.module.ts - Users · User profiles, teacher subjects, and user-facing account data.
backend/src/modules/users/users.module.ts - Tasks · Assignments, submissions, comments, grading, and analytics.
backend/src/modules/tasks/tasks.module.ts - Farm · Plants, production, inventory, boosters, and farm activity.
backend/src/modules/farm/farm.module.ts - Pet · Pets, items, and pet interactions.
backend/src/modules/pet/pet.module.ts - Gamification · Achievements, progress, zones, and groups supporting game/learning flow.
backend/src/modules/achievements/achievements.module.ts - Storage · File upload and retrieval boundary for binary assets.
backend/src/modules/storage/storage.module.ts - Ops APIs · Monitoring and health endpoints.
backend/src/modules/monitoring/monitoring.module.ts
Runtime & Ops
Deployment, proxying, storage, observability, and database infrastructure.
- PostgreSQL · Primary transactional database and schema boundary.
backend/database/schema.sql - Redis · Socket.IO adapter and pub/sub layer for realtime fanout.
backend/src/adapters/redis-io.adapter.ts - Nginx · Front door for routing, SSL, and load balancing.
nginx.conf - Deploy · Docker Compose and Kubernetes runtime definitions.
docker-compose.yml - Observability · Prometheus, Grafana, Loki, and ELK configuration.
monitoring/prometheus/prometheus.yml
Connections 38
- 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.