1. Problem Statement & Multi-Tenant Requirements
Educational institutions require a unified software platform that can handle complex academic schedules, student grading, tuition fee billing, and real-time attendance across multiple schools without data leakage. Key requirements included:
- Strict Multi-Tenant Data Isolation: Enforcing tenant tenancy (`tenant_id`) at the database session level to prevent cross-school data leakage.
- Granular Role-Based Access Control (RBAC): Hierarchical permissions separating Superadmin, Principal, Teacher, Student, and Parent roles across 19 modular features.
- High-Speed Modular Backend: Decoupled Go Clean Architecture allowing independent feature extensions (Billing, Academics, Exam grading) without monolithic regressions.
2. System Architecture & Layered Design
[Next.js Client] ──(HTTPS/REST + JWT)──▶ [Nginx Reverse Proxy & SSL]
│
▼
[Go Backend (Clean Architecture)]
├── Delivery Layer (Gin HTTP Handlers)
├── Usecase Layer (Business Logic & RBAC)
└── Repository Layer (PostgreSQL Multi-Tenant DAO)
│
▼
[PostgreSQL Database (Tenant Schemas)]
3. Key Engineering Decisions
- Why Clean Architecture (Uncle Bob Pattern)? Clear separation of concerns ensures that switching database drivers, caching layers, or transport protocols (REST to gRPC) requires zero changes to core business domain entities.
- Why JWT with Tenant Claims? Stateless authentication embeds `tenant_id` and `role_permissions` inside cryptographically signed JWT tokens, allowing Go middleware to enforce RBAC without querying the database on every request.
- Why Next.js SSR + Go Backend? Provides server-side rendering for optimal frontend performance and SEO while offloading heavy concurrent data processing to compiled Go microservices.
4. Architecture Trade-offs
✅ Clean Architecture (Pros)
- High testability with mocked repository interfaces.
- Modular codebase supporting 19 independent feature squads.
⚠️ Struct & DTO Mapping (Cons)
- Increased initial boilerplate mapping between domain models and HTTP payloads.