Diagram 01
System Architecture
A layered architecture with a single entry point — Nginx as the sole internet-facing gateway, routing requests through an API Gateway to four independent microservices, each owning its own database.
The system is organised into three functional tiers plus one entry layer. The Client tier consists of a Next.js web application and a React Native mobile app — both access the system exclusively through an Nginx Reverse Proxy that handles HTTPS termination (Let's Encrypt), port 80/443, and acts as the sole internet-facing exposure point. Behind Nginx sits the API Gateway (Express, port 3000), which owns all cross-cutting concerns: request routing, JWT validation, RBAC permission checks, and rate limiting. The Business tier comprises four independently deployable microservices — Auth, Staff, Research, and Notification — running on ports 3001–3004. The Data tier follows a strict Database-per-Service pattern: each service owns a private PostgreSQL instance, enforcing complete data isolation.
Diagram 02
Shared Infrastructure
Cross-service infrastructure components — event backbone, caching, file storage, email delivery, and real-time channels — that are shared across the system but kept outside any single service's domain.
Apache Kafka serves as the system's event
backbone. Three services — Auth, Staff, and Research — act as
event publishers; Notification Service is the
sole consumer, processing all incoming events to dispatch alerts.
Redis is shared between Auth Service (storing
refresh tokens, password-reset tokens, and login lock counters)
and Notification Service (caching unread notification counts per
user). Cloudflare R2 — S3-compatible object
storage — holds research paper PDFs and staff avatar images,
keeping binary assets out of PostgreSQL.
Gmail SMTP is used exclusively by Notification
Service to send transactional emails for significant system
events. Finally, Socket.io maintains
bidirectional connections from Notification Service to all
connected clients, enabling real-time push notifications and
force_logout events when an account is locked or
revoked.
Diagram 03
Kafka Event Flow
13 Kafka topics, each mapping to one business event type — named in
kebab-case following <entity>-<action> convention,
declared centrally in
topics.ts, and referenced uniformly by all producers and the single
consumer.
The system defines 13 Kafka topics, each
corresponding to exactly one business event type. Topics follow
the kebab-case convention with the structure
<entity>-<action> — for example
research-approved or user-blocked — so
that each topic name is self-documenting and debuggable without
needing supplementary docs. All topics are declared in a single
topics.ts file owned by Notification
Service. The three producer services (Auth, Staff, Research)
import constants from this file, ensuring naming consistency
across the entire event mesh. Notification Service, as the sole
consumer, subscribes to all 13 topics and maps each to the
appropriate notification handler.
