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) on ports 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 checks and rate limiting. The Business tier comprises four independently deployable microservices — Auth, Staff, Research and Notification — 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 — event backbone, caching, file storage, email delivery and real-time channels — shared across the system but kept outside any single service's domain.
Apache Kafka serves as the event backbone. Three
services — Auth, Staff and Research — act as publishers;
Notification Service is the sole consumer,
processing all events to dispatch alerts. Redis is
shared between Auth (refresh tokens, password-reset tokens, login
lock counters) and Notification (unread-count cache).
Cloudflare R2 — S3-compatible object storage —
holds research PDFs and staff avatars, keeping binary assets out of
PostgreSQL. Gmail SMTP is used by Notification
Service to send transactional emails. Finally,
Socket.io maintains bidirectional connections for
real-time push notifications and force_logout events
when an account is locked.
Diagram 03
Kafka Event Flow
13 Kafka topics, each mapping to one business event — named in kebab-case following the entity-action convention, declared centrally, and referenced uniformly by all producers and the single consumer.
The system defines 13 Kafka topics, each
corresponding to exactly one business event. Topics follow a
kebab-case entity-action structure —
for example research-approved or
user-blocked — so each name is self-documenting and
debuggable without extra docs. All topics live in a single
topics.ts owned by Notification
Service; the three producers import constants from it, ensuring
naming consistency across the event mesh. Notification Service, the
sole consumer, subscribes to all 13 topics and maps each to the
appropriate handler.
Diagram 04
Deployment & CI/CD
A fully automated, push-to-deploy pipeline. Every push to main triggers GitHub Actions to build Docker images, push them to Docker Hub, and deploy to a production VPS over SSH — served through Nginx with HTTPS at hau.bian.io.vn.
The whole system runs on a production VPS (Ubuntu),
served at hau.bian.io.vn over HTTPS. A single
Nginx reverse proxy terminates TLS (Let's Encrypt)
and is the only port exposed to the internet — every microservice,
database, Kafka and Redis stays private inside the Docker network.
Deployment is fully automated with GitHub Actions:
a path filter detects which service changed, builds only that
image, and pushes it to Docker Hub. A deploy job
then connects to the VPS over SSH, syncs the latest
code, pulls the fresh images and restarts the stack with
docker compose — a zero-touch, push-to-deploy workflow
with no manual server steps. The
same Nginx reverse proxy fronts both local development and
production, giving an identical single-entry-point topology
across environments — the two only differ in TLS and upstream
targets.
