# Architecture

## Goals

1. Arabic RTL first, responsive, accessible web experience.
2. Multi-project architecture supporting poultry, eggs, agriculture, orchards, livestock, food production and warehouses.
3. Strong separation between public project information, private investor information, KYC data, documents and administration.
4. Backend-enforced authorization and immutable audit history for sensitive actions.
5. Production architecture with legal/financial activation gates kept OFF by default.

## Selected stack

- Web: Next.js + TypeScript + Tailwind + shadcn/ui
- API: NestJS + TypeScript + REST/OpenAPI
- Database: PostgreSQL
- Cache/queue: Redis + BullMQ-compatible queue layer
- Storage: private S3-compatible object storage with signed URLs
- Mobile: Flutter (future phase; tooling unavailable in current workspace)
- Current edge/runtime: Namecheap cPanel Passenger/Node application
- Current deployment: combined `server.cjs` serves Next.js + NestJS on one subdomain
- Future scale path: VPS/cloud with Nginx, Docker, Redis workers and private services

## Logical architecture

Current cPanel: Client → HTTPS → Passenger/Node (`server.cjs`) → Next.js + NestJS `/api` → PostgreSQL

Future VPS: Client → HTTPS → Nginx → Web / API → PostgreSQL + Redis + Private Object Storage

On the cPanel release, bounded background work is initiated by one authenticated Cron runner every few minutes. The runner handles session/OTP cleanup, document-expiry scans, task/report scans and health snapshots; permanent queue workers are deferred. On a future VPS, the same application services can be dispatched through Redis/BullMQ workers. Sensitive compliance decisions requiring human/legal judgment remain manual-review capable.

## Bounded contexts

- Identity & Access
- Users & Devices
- KYC
- Compliance / AML support
- Projects & Verification
- Farm Operations
- Poultry & Egg Production
- Inventory / Suppliers / Customers
- Sales / Expenses / Accounting
- Investment Interest & Requests
- Contracts
- Payment Abstraction
- Documents / Data Room
- Reports / Analytics
- Operational AI / Anomaly Insights
- PWA / Mobile Web
- System Health / Backup Tracking
- Notifications / Support
- CMS
- Audit / Security

## Data classification

### Public
Project summary, approximate location, explicitly approved public documents/reports and approved public metrics.

### Restricted
Investor requests, internal reports, business financials, project operational details and non-public documents.

### Highly restricted
KYC identity documents, precise land location, personal financial data, contracts, payment records and security telemetry.

## Compliance gates

The backend owns the authoritative gates. Frontend state is informational only.

- LIVE_INVESTMENT=false
- COLLECT_FUNDS=false
- LIVE_PAYMENTS=false

A future activation operation requires authenticated privileged administration, audit logging, legal approval evidence and production configuration change control.