How psmri/ubi-beneficiary-backend works
Project Type and Purpose
• This is a NestJS-based backend monolith for the “UBI Beneficiary” application. Its primary role is to expose RESTful APIs to serve a front-end or other clients, orchestrate business logic (user management, custom fields, OTP, housekeeping), handle credentials issuance (via wallet service), and manage data persistence in PostgreSQL (with Hasura support).
File Structure Analysis
• Top-level: Dockerfile, docker-compose.yml, deploy scripts, CI/CD (.github, Jenkinsfile) → deployment infrastructure.
• Migrations & schema.pgsql → database schema management for Postgres.
• schemas/credentials → JSON schemas for verifiable credentials.
• scripts/* → operational scripts (encryption migration, key rotation).
• src/ → application code:
• app.module.ts, main.ts → NestJS bootstrap.
• common/ → cross-cutting concerns (interceptors, filters, guards, middleware, decorators, helpers).
• logger/ → centralized logging.
• modules/ → feature modules (auth, users, admin, customfields, otp, housekeeping, user_roles, content).
• services/ → integrations with external systems (Keycloak, Hasura, Proxy, Wallet).
• migrations, tests, DTOs, entities → data models and testing.
README Insights
• Confirms it’s the backend for UBI Beneficiary App with links to environment variables, DB setup, build & deploy procedures.
Key Components
a. NestJS API Layer (API Gateway)
• main.ts/app.module.ts launches HTTP server.
• common middleware (auth.middleware), interceptors, exception filters applied.
• Auth Module ↔ Keycloak Service (external OAuth2)
• Users Module (includes DTOs, entities, cron jobs for profile populating and status updates)
• Admin Module
• CustomFields Module
• OTP Module
• Housekeeping Module
• UserRoles Module
• Content Module (caching & content CRON refresh)
c. External Integrations
• Keycloak (Identity Provider)
• Hasura (GraphQL or direct DB access)
• Proxy Service (network API proxy)
• Wallet Service (credential issuance)
d. Data Layer
• PostgreSQL Database
• migrations + schema.pgsql
• tables for user, roles, docs, consent, network cache, etc.
• JSON Schemas for credentials (validation)
e. Operational Infrastructure
• Docker / docker-compose
• CI/CD pipelines (.github workflows, Jenkinsfile)
• Scripts for key rotation & encryption
Relationships & Data Flows
• Client → HTTP(S) → NestJS API
• API → Auth Module → Keycloak for token validation/refresh
• API → Services
• Hasura Service ↔ GraphQL endpoint → DB
• Proxy Service → External Network APIs
• Wallet Service → VC issuance platform
• Modules → Entities → Repository/ORM → DB
• Cron jobs (inside Users & Content modules) → scheduled tasks → internal services/DB
• Logging Service → optional Sentry or file/console
• CI/CD → build Docker image → deploy to environment
Architectural Patterns & Principles
• Modular architecture (NestJS modules)
• Layered pattern: Controller → Service → Repository (entities)
• Cross-cutting concerns centralized in common/
• Dependency injection via NestJS
• Configuration-driven (env variables, .env.example, nest-cli.json)
• Automated migrations & scripts for schema evolution