# uniz-rguktong/uniz-master architecture

> Architecture diagram of the GitHub repository uniz-rguktong/uniz-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uniz-rguktong/uniz-master
- Repository: https://github.com/uniz-rguktong/uniz-master

## Overview

1. **Repository shape**
   - This is a monorepo for the UniZ university platform, split into multiple deployable apps, shared infrastructure, test/seed tooling, and documentation.
   - The architecture is not a single app: it is a small platform with separate frontends, backend services, and ops automation.

2. **Primary user-facing surfaces**
   - `apps/uniz-portal` is the main authenticated web portal for students, faculty, and admins. It is a React/Vite frontend with PWA, push notifications, polling, and many role-specific pages.
   - `apps/uniz-landing` is the public marketing/content website.
   - `apps/uniz-gateway` appears to be a lightweight public entry/front-door app, but the real edge behavior is defined in the infra layer.

3. **Public content backend**
   - `apps/uniz-landing-backend` is a separate Python service, likely FastAPI-based, that powers the landing site’s dynamic content.
   - It has routers for home, academics, departments, institute, analytics, and notifications, so it is the content-management/backend-of-record for the public site rather than part of the authenticated portal system.

4. **Core backend service boundaries**
   - The main business logic is split into Node.js/TypeScript microservices:
     - `uniz-auth` for authentication, OTP, password reset, JWT issuance, role management.
     - `uniz-user` for profiles, bulk import, CMS/user operations, and queue-based work.
     - `uniz-academics` for attendance, grades, curriculum, semester registration, seating, faculty/subject workflows.
     - `uniz-outpass` for request/grievance approvals and outpass-related flows.
     - `uniz-files` for file upload and file-related access.
     - `uniz-mail` for email delivery and mail-triggered workflows.
     - `uniz-notifications` for notification persistence/event handling.
     - `uniz-cron` for scheduled cleanup and maintenance jobs.
   - Each service owns a bounded domain; the repo is organized around those functional seams.

5. **Authentication and authorization flow**
   - JWT is the shared authentication mechanism across services, with per-service auth middleware and shared role enums/schemas.
   - Most services also have rate limiting, validation, and attribution middleware, indicating a consistent request-processing pipeline.
   - `turnstile` utilities show bot protection on public-facing auth/registration paths.
   - The portal is role-driven, with UI pages and service access tailored for webmaster, faculty, student, dean, warden, SWO, etc.

6. **Data persistence model**
   - Persistence is centered on PostgreSQL with Prisma in the Node services.
   - Each service has its own Prisma schema/migrations, which suggests service-owned data rather than one shared monolithic schema.
   - `prisma/seed.ts` and many import/verification scripts show that the system depends heavily on data seeding and bulk synchronization for institutional records.

7. **Caching, queues, and background work**
   - Redis is used as the shared fast-state layer for queues, temporary tokens, rate-limiting, and ephemeral workflow coordination.
   - Several services have queue controllers, worker scripts, or Redis utilities, so non-immediate tasks are offloaded from request/response paths.
   - The `uniz-user` and `uniz-academics` services include worker/helper scripts for bulk imports and operational jobs, and `uniz-cron` exists specifically to run scheduled cleanup/maintenance tasks.

8. **Frontend data access patterns**
   - The portal is not just a passive UI: it contains API clients, network interceptors, polling hooks, WebSocket hooks, CSV upload flows, and push-notification support.
   - This implies a mixed interaction model: standard REST for most actions, plus background refresh and event-driven updates for dashboards and operational views.
   - The portal also includes reusable UI libraries and many domain pages, which makes it the orchestration layer for the authenticated experience.

9. **Edge, routing, and trust boundaries**
   - Production infrastructure uses Nginx and Kubernetes manifests under `infra/core-infra/kubernetes`, with ingress/gateway resources defining the external access path.
   - The README’s “edge-first” posture matches the repo layout: public traffic terminates at the edge, then reaches internal services over private cluster networking.
   - The gateway layer is where TLS, routing, and CORS/security controls are concentrated rather than inside every frontend.

10. **Infrastructure and deployment**
    - The repo includes Dockerfiles for each app, Compose files for local/prod-style setups, and Kustomize-based Kubernetes manifests for deployment.
    - GitHub Actions are used for deployment automation, and there are scripts for VPS redeploy, secret syncing, seeding, and local setup.
    - Environment separation is explicit: local secrets are propagated from a gitignored file, while production secrets are injected from the VPS during deploy.

11. **Operational tooling and verification**
    - The repository includes extensive scripts and test data for load tests, import validation, remediation flows, and bulk data generation.
    - This is a strong signal that data migration, batch onboarding, and operational verification are first-class concerns in the architecture.
    - The `brain/`, `docs/`, `postman/`, and `tests/` folders support system understanding, API validation, and release readiness.

12. **How to draw the architecture**
    - A good diagram should show two client planes: public website traffic and authenticated portal traffic.
    - Both enter through an edge/gateway layer, then branch to independent domain services.
    - Each service owns its own persistence and uses Redis for fast state or async work, while the portal consumes those services through APIs and real-time/polling hooks.
    - The landing backend should be shown separately from the core microservices, because it serves a different audience and has a different runtime stack.

Main entry points: [`infra/core-infra/kubernetes/base`](https://github.com/uniz-rguktong/uniz-master/tree/main/infra/core-infra/kubernetes/base) (Kubernetes), [`apps/uniz-portal`](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-portal) (UniZ Portal), [`scripts/seed-local.ts`](https://github.com/uniz-rguktong/uniz-master/blob/main/scripts/seed-local.ts) (Seed & Sync), [`apps/uniz-auth`](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-auth) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_portal["UniZ Portal<br/>React/Vite PWA"]
  node_landing["UniZ Landing<br/>React site"]
  node_gateway["UniZ Gateway<br/>edge app"]
end

subgraph group_services["Backend services"]
  node_landing_backend["Landing Backend<br/>FastAPI service"]
  node_auth["Auth Service<br/>Node auth"]
  node_user["User Service<br/>Node user"]
  node_academics["Academics Service<br/>Node academics"]
  node_outpass["Outpass Service<br/>Node approvals"]
  node_files["Files Service<br/>Node file API"]
  node_mail["Mail Service<br/>Node mailer"]
  node_notifications["Notification Service<br/>Node notifications"]
  node_cron["Cron Service<br/>Node scheduler"]
end

subgraph group_infra["Infrastructure"]
  node_nginx{{"Nginx Edge<br/>reverse proxy<br/>[nginx.prod.conf]"}}
  node_k8s{{"Kubernetes<br/>cluster manifests"}}
  node_compose{{"Compose Stack<br/>local/prod compose<br/>[docker-compose.yml]"}}
end

subgraph group_ops["Ops and verification"]
  node_deploy["Deploy Automation<br/>GitHub Actions<br/>[deploy.yml]"]
  node_seeding["Seed & Sync<br/>data tooling<br/>[seed-local.ts]"]
  node_verification["Verification Kits<br/>tests and postman"]
end

node_portal -->|"serves through"| node_nginx
node_landing -->|"serves through"| node_nginx
node_gateway -->|"front door"| node_nginx
node_nginx -->|"routes to"| node_k8s
node_k8s -->|"deploys"| node_auth
node_k8s -->|"deploys"| node_user
node_k8s -->|"deploys"| node_academics
node_k8s -->|"deploys"| node_outpass
node_k8s -->|"deploys"| node_files
node_k8s -->|"deploys"| node_mail
node_k8s -->|"deploys"| node_notifications
node_k8s -->|"deploys"| node_cron
node_landing_backend -->|"deploys via"| node_k8s
node_portal -->|"calls"| node_auth
node_portal -->|"calls"| node_user
node_portal -->|"calls"| node_academics
node_portal -->|"calls"| node_outpass
node_portal -->|"calls"| node_files
node_portal -->|"consumes"| node_notifications
node_portal -.->|"triggers"| node_mail
node_auth -.->|"seeded by"| node_seeding
node_user -.->|"seeded by"| node_seeding
node_academics -.->|"seeded by"| node_seeding
node_outpass -.->|"seeded by"| node_seeding
node_notifications -.->|"seeded by"| node_seeding
node_deploy -->|"drives"| node_compose
node_deploy -->|"applies"| node_k8s
node_verification -.->|"validates"| node_portal
node_verification -.->|"validates"| node_auth
node_verification -.->|"validates"| node_academics

click node_portal "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-portal"
click node_landing "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-landing"
click node_gateway "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-gateway"
click node_landing_backend "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-landing-backend"
click node_auth "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-auth"
click node_user "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-user"
click node_academics "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-academics"
click node_outpass "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-outpass"
click node_files "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-files"
click node_mail "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-mail"
click node_notifications "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-notifications"
click node_cron "https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-cron"
click node_nginx "https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/nginx/nginx.prod.conf"
click node_k8s "https://github.com/uniz-rguktong/uniz-master/tree/main/infra/core-infra/kubernetes/base"
click node_compose "https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/docker-compose.yml"
click node_deploy "https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/.github/workflows/deploy.yml"
click node_seeding "https://github.com/uniz-rguktong/uniz-master/blob/main/scripts/seed-local.ts"
click node_verification "https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/postman/UniZ Development Collection.postman_collection.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_portal,node_landing,node_gateway toneBlue
class node_landing_backend,node_auth,node_user,node_academics,node_outpass,node_files,node_mail,node_notifications,node_cron toneAmber
class node_nginx,node_k8s,node_compose toneMint
class node_deploy,node_seeding,node_verification toneRose
```

## Components

### Client apps

Public site, authenticated portal, and gateway front doors

- [UniZ Portal](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-portal): React/Vite PWA · Authenticated web portal with role-specific dashboards, polling, push notifications, and API orchestration · `apps/uniz-portal`
- [UniZ Landing](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-landing): React site · Public marketing and content website for the university · `apps/uniz-landing`
- [UniZ Gateway](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-gateway): edge app · Lightweight public entry app that sits behind the infra routing layer · `apps/uniz-gateway`

### Backend services

Domain microservices and the landing backend

- [Landing Backend](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-landing-backend): FastAPI service · Python content backend for public site data such as academics, departments, institute, analytics, and notifications · `apps/uniz-landing-backend`
- [Auth Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-auth): Node auth · Authentication, OTP, password reset, JWT issuance, and role management · `apps/uniz-auth`
- [User Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-user): Node user · Profiles, bulk import, CMS/user operations, and queued background work · `apps/uniz-user`
- [Academics Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-academics): Node academics · Attendance, grades, curriculum, semester registration, seating, and faculty workflows · `apps/uniz-academics`
- [Outpass Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-outpass): Node approvals · Outpass, request, grievance, and approval-log flows · `apps/uniz-outpass`
- [Files Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-files): Node file API · File upload and file access handling for service workflows · `apps/uniz-files`
- [Mail Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-mail): Node mailer · Email delivery and mail-triggered workflows · `apps/uniz-mail`
- [Notification Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-notifications): Node notifications · Notification persistence and event handling for the platform · `apps/uniz-notifications`
- [Cron Service](https://github.com/uniz-rguktong/uniz-master/tree/main/apps/uniz-cron): Node scheduler · Scheduled cleanup and maintenance jobs · `apps/uniz-cron`

### Infrastructure

Deployment, routing, and cluster manifests

- [Nginx Edge](https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/nginx/nginx.prod.conf): reverse proxy · TLS termination, routing, and gateway/security controls at the edge · `infra/core-infra/nginx/nginx.prod.conf`
- [Kubernetes](https://github.com/uniz-rguktong/uniz-master/tree/main/infra/core-infra/kubernetes/base): cluster manifests · Service, ingress, gateway, and job manifests for cluster deployment · `infra/core-infra/kubernetes/base`
- [Compose Stack](https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/docker-compose.yml): local/prod compose · Containerized runtime definitions for local and VPS-style deployments · `infra/core-infra/docker-compose.yml`

### Ops and verification

Seed, test, and operational tooling

- [Deploy Automation](https://github.com/uniz-rguktong/uniz-master/blob/main/infra/core-infra/.github/workflows/deploy.yml): GitHub Actions · Deployment workflows and redeploy scripts for the monorepo · `infra/core-infra/.github/workflows/deploy.yml`
- [Seed & Sync](https://github.com/uniz-rguktong/uniz-master/blob/main/scripts/seed-local.ts): data tooling · Seed scripts, bulk import tooling, and secret/config sync helpers · `scripts/seed-local.ts`
- [Verification Kits](https://github.com/uniz-rguktong/uniz-master/blob/HEAD/infra/core-infra/postman/UniZ%20Development%20Collection.postman_collection.json): tests and postman · Load tests, API collections, and remediation/validation data for release readiness · `infra/core-infra/postman/UniZ Development Collection.postman_collection.json`

## Connections

- UniZ Portal → Nginx Edge: serves through · Authenticated traffic reaches the edge before internal services
- UniZ Landing → Nginx Edge: serves through · Public website traffic is routed via the edge layer
- UniZ Gateway → Nginx Edge: front door · Gateway behavior is defined by the shared edge/routing tier
- Nginx Edge → Kubernetes: routes to · Ingress and service routing are declared in cluster manifests
- Kubernetes → Auth Service: deploys · Cluster resources run the auth service
- Kubernetes → User Service: deploys · Cluster resources run the user service
- Kubernetes → Academics Service: deploys · Cluster resources run the academics service
- Kubernetes → Outpass Service: deploys · Cluster resources run the outpass service
- Kubernetes → Files Service: deploys · Cluster resources run the files service
- Kubernetes → Mail Service: deploys · Cluster resources run the mail service
- Kubernetes → Notification Service: deploys · Cluster resources run the notification service
- Kubernetes → Cron Service: deploys · Cluster resources run scheduled jobs
- Landing Backend → Kubernetes: deploys via · The public content backend is deployed alongside platform services
- UniZ Portal → Auth Service: calls · Portal login and session flows depend on shared JWT auth
- UniZ Portal → User Service: calls · Portal uses user/profile and CMS APIs
- UniZ Portal → Academics Service: calls · Portal drives academic, attendance, and registration workflows
- UniZ Portal → Outpass Service: calls · Portal uses request and grievance workflows
- UniZ Portal → Files Service: calls · Portal uploads and retrieves files through the files service
- UniZ Portal → Notification Service: consumes · Portal surfaces notification updates and event-driven UX
- UniZ Portal → Mail Service: triggers · Some portal actions initiate email workflows indirectly
- Auth Service → Seed & Sync: seeded by · Auth relies on seed and repair scripts for institutional data
- User Service → Seed & Sync: seeded by · User bulk import and synchronization are first-class operations
- Academics Service → Seed & Sync: seeded by · Academics depends on curriculum, subject, and faculty seed data
- Outpass Service → Seed & Sync: seeded by · Approval workflows use preloaded institutional records
- Notification Service → Seed & Sync: seeded by · Notification state is initialized and repaired through data tooling
- Deploy Automation → Compose Stack: drives · Deployment automation uses container stack definitions
- Deploy Automation → Kubernetes: applies · CI/CD targets Kubernetes manifests for production rollout
- Verification Kits → UniZ Portal: validates · Load tests and API collections exercise the user-facing portal flows
- Verification Kits → Auth Service: validates · Test assets cover authentication and login behavior
- Verification Kits → Academics Service: validates · Validation data covers attendance, grades, and semester flows
