DevOps & Deployment

Production Deployment Architecture & Topology

Comprehensive architecture overview of YeneSchool's production container topology — PostgreSQL with pgvector, PgBouncer, Redis BullMQ, NestJS, Next.js, and Nginx.

Production Deployment Architecture & Topology

YeneSchool is engineered for high availability, fast response times under Ethiopian internet latency conditions, and seamless vertical and horizontal scaling. The production stack is containerized with Docker and Docker Compose, employing battle-tested services for caching, connection pooling, and background worker queues.

1. Container Topology & Service Inventory

Container Service	Base Image	Role & Responsibilities
`nginx`	`nginx:alpine`	SSL/TLS termination, request gzip compression, path routing, and authenticated static uploads protection.
`frontend`	Custom Next.js 14+	Server-Side Rendering (SSR), App Router, client-side caching with React Query, PWA service worker delivery.
`backend`	Custom NestJS / Node 20	REST API controllers, JWT authentication, RBAC authorization, BullMQ job dispatchers, and Prisma ORM client.
`redis`	`redis:7-alpine`	BullMQ task queues, rate-limiting counters, and token revocation blacklists.
`pgbouncer`	`edoburu/pgbouncer`	Transaction-mode connection multiplexing, bounding active PostgreSQL processes during peak traffic.
`postgres`	`pgvector/pgvector:pg16`	Relational multi-tenant database with vector extensions for AI document semantic search.

2. Port & Network Allocation

Frontend Web UI: Bound to host port 8000 via Nginx (and port 443 in HTTPS environments).
Backend REST API: Exposed on port 8001 (internal sms_network communication).
PostgreSQL Database: Exposed on host port 5433 (mapped internally to 5432 to avoid conflicts with existing local Postgres instances).
Redis Cache & Queues: Exposed internally on port 6379.
PgBouncer Pooler: Operates on internal port 6432.

3. Recommended Production Hardware Sizing

For an institution or multi-tenant deployment hosting between 1,000 and 10,000 active students:

CPU: 4 vCPUs (x86_64 or ARM64)
Memory (RAM): 16 GB ECC RAM
- PostgreSQL: shared_buffers=1GB, effective_cache_size=3GB
- PgBouncer: Max 200 server connections
- NestJS & Next.js: 4 GB allocation with PM2 cluster mode
- Redis: 2 GB maxmemory with allkeys-lru eviction policy
Disk Storage: 100 GB+ NVMe SSD storage with automated daily snapshot backups

System Monitoring

Monitoring BullMQ job queues, Redis cache, database connection pools, WebSocket real-time presence, and platform audit logs.

Production Docker Runbook

Step-by-step runbook for deploying YeneSchool in production using Docker Compose — secrets setup, database migrations, and Nginx SSL configuration.