Architecture — School MIS Docs

High-level topology

┌─────────────────┐ │ React Web App │ │ Admin + Parent │ └────────┬────────┘ │ HTTPS ┌────────▼────────┐ │ api-gateway │ JWT, rate limit, CORS └────────┬────────┘ ┌───────────────────┼───────────────────┐ │ │ │ auth-service organization-service student-service fee-service finance-service academic-service attendance inventory-service notice-service health-service notification file-service report-service │ │ │ └───────────────────┼───────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ PostgreSQL RabbitMQ MinIO (per service) (events) (files)

Microservices

Service	Port (dev)	Database	Responsibility
`api-gateway`	8080	—	Route, JWT validation, request logging
`auth-service`	8081	auth_db	Users, roles, parent accounts, guardian links, JWT issue
`organization-service`	8082	org_db	School, campuses, academic years, terms, classes
`student-service`	8083	student_db	Students, guardians, enrollments, requirements checklist
`fee-service`	8084	fee_db	Fee structures, invoices, payment claims, payments, receipts, defaulters
`finance-service`	8085	finance_db	Chart of accounts, journal entries, P&L, balance sheet
`academic-service`	8086	academic_db	Subjects, marks, grading schemes, report cards, homework
`attendance-service`	8087	attendance_db	Daily attendance, summaries
`health-service`	8093	health_db	Student health records, parent confirmation, doctor's notes, nurse access, audit log
`inventory-service`	8088	inventory_db	Stock, uniforms, issuance
`notice-service`	8089	notice_db	Notices, document distribution, audience targeting
`notification-service`	8090	notification_db	SMS (Africa's Talking), email, delivery webhooks
`file-service`	8091	file_db	MinIO uploads, presigned URLs, receipt PDF generation
`report-service`	8092	report_db	Director dashboards, aggregated read models

Payment claim flow (cross-service)

Parent Portal → api-gateway → fee-service (create claim) fee-service → RabbitMQ: PaymentClaimSubmitted notification-service → SMS to bursar Bursar Admin → fee-service (approve) fee-service → DB: payment + allocation (transaction) fee-service → RabbitMQ: PaymentReceived ├→ file-service: generate receipt PDF ├→ notice-service: add to parent document library ├→ notification-service: SMS parent └→ finance-service: post journal entry

Gateway route map

/api/v1/auth/**           → auth-service
/api/v1/org/**            → organization-service
/api/v1/students/**       → student-service
/api/v1/fees/**           → fee-service
/api/v1/portal/**         → fee-service + notice-service (BFF optional in report-service)
/api/v1/admin/**          → respective admin routes per service
/api/v1/files/**          → file-service
/api/v1/notifications/**  → notification-service (internal + webhooks)

Communication patterns

Synchronous: REST via gateway for reads/writes that need immediate response
Asynchronous: RabbitMQ topic exchange school.events for side effects (notifications, PDF, ledger)
Saga: Payment approval uses local DB transaction + outbox pattern; consumers idempotent
No shared DB: Each service owns its schema; cross-service IDs are UUIDs only

Security

JWT access token (15 min) + refresh token (7 days) from auth-service
Roles: SYSTEM_ADMIN, DIRECTOR, BURSAR, TEACHER, RECEPTION, PARENT, HEALTH_RECORDS_VIEWER
Health Records Access group — explicit staff list; only members + director view health-service data
Campus-scoped roles via campus_id claim in JWT
Parent endpoints enforce guardian–student link in fee-service
All payment state changes append to immutable audit log

Docker deployment

Phase 1 (Core only):
  - gateway + auth, organization, student, file, notification (6 services)
  - postgres×6, rabbitmq, redis, minio, react-web

Full product (modules 1–12):
  - gateway, 14 services, postgres×14

With extended modules 13–22 (when sold):
  - up to 24 additional services — see extended roadmap

Extended roadmap services (13–22)

Service	Module
`transport-service`	13 Transport
`boarding-service`	14 Boarding & hostel
`scholarship-service`	15 Scholarships
`welfare-service`	16 Discipline & welfare
`timetable-service`	17 Timetable
`chat-service`	18 Official chat
`calendar-service`	19 Events & calendar
`hr-service`	20 HR & payroll
`elearning-service`	21 E-learning
`library-service`	22 Library

Extended modules roadmap · Core Foundation plan

Technology versions (target)

Java 21, Spring Boot 3.3+, Spring Cloud Gateway
React 18 + TypeScript, Vite
PostgreSQL 16
RabbitMQ 3.13
MinIO latest compatible