How uniz-rguktong/uniz-master works
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: base Kubernetes · uniz-portal UniZ Portal · seed-local.ts Seed & Sync · uniz-auth Auth Service
Components 18
Client apps
Public site, authenticated portal, and gateway front doors
- UniZ Portal · Authenticated web portal with role-specific dashboards, polling, push notifications, and API orchestration
apps/uniz-portal - UniZ Landing · Public marketing and content website for the university
apps/uniz-landing - UniZ Gateway · Lightweight public entry app that sits behind the infra routing layer
apps/uniz-gateway
Backend services
Domain microservices and the landing backend
- Landing Backend · Python content backend for public site data such as academics, departments, institute, analytics, and notifications
apps/uniz-landing-backend - Auth Service · Authentication, OTP, password reset, JWT issuance, and role management
apps/uniz-auth - User Service · Profiles, bulk import, CMS/user operations, and queued background work
apps/uniz-user - Academics Service · Attendance, grades, curriculum, semester registration, seating, and faculty workflows
apps/uniz-academics - Outpass Service · Outpass, request, grievance, and approval-log flows
apps/uniz-outpass - Files Service · File upload and file access handling for service workflows
apps/uniz-files - Mail Service · Email delivery and mail-triggered workflows
apps/uniz-mail - Notification Service · Notification persistence and event handling for the platform
apps/uniz-notifications - Cron Service · Scheduled cleanup and maintenance jobs
apps/uniz-cron
Infrastructure
Deployment, routing, and cluster manifests
- Nginx Edge · TLS termination, routing, and gateway/security controls at the edge
infra/core-infra/nginx/nginx.prod.conf - Kubernetes · Service, ingress, gateway, and job manifests for cluster deployment
infra/core-infra/kubernetes/base - Compose Stack · 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 · Deployment workflows and redeploy scripts for the monorepo
infra/core-infra/.github/workflows/deploy.yml - Seed & Sync · Seed scripts, bulk import tooling, and secret/config sync helpers
scripts/seed-local.ts - Verification Kits · Load tests, API collections, and remediation/validation data for release readiness
infra/core-infra/postman/UniZ Development Collection.postman_collection.json
Connections 30
- 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