# psmri/ubi-beneficiary-backend architecture

> Architecture diagram of the GitHub repository psmri/ubi-beneficiary-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psmri/ubi-beneficiary-backend
- Repository: https://github.com/psmri/ubi-beneficiary-backend

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% NestJS Application Layer
    subgraph "NestJS Application"
        direction TB
        API["NestJS API Layer\n(main.ts, app.module.ts)"]:::internal
        Common["Common (interceptors, filters, guards,\nmiddleware, decorators, helpers)"]:::internal
        Logger["Logging Service"]:::internal

        subgraph "Feature Modules"
            direction TB
            Auth["Auth Module"]:::internal
            Users["Users Module"]:::internal
            Admin["Admin Module"]:::internal
            CustomFields["CustomFields Module"]:::internal
            OTP["OTP Module"]:::internal
            Housekeeping["Housekeeping Module"]:::internal
            UserRoles["UserRoles Module"]:::internal
            Content["Content Module"]:::internal
        end

        subgraph "Integration Services"
            direction TB
            Keycloak["Keycloak Service"]:::external
            Hasura["Hasura Service"]:::external
            Proxy["Proxy Service"]:::external
            Wallet["Wallet Service"]:::external
        end
    end

    %% External Database and Schemas
    subgraph "Database"
        direction TB
        Postgres["PostgreSQL DB"]:::database
        Migrations["Data Migrations & Schema"]:::database
        JSONSchemas["JSON Schemas for Credentials"]:::database
    end

    %% Deployment & CI/CD
    Infra["CI/CD & Deployment\n(Docker, Scripts, Jenkins, GitHub)"]:::infra

    %% Data Flows
    Client["Client (Front-end or Other)"]:::external
    Client -->|"HTTP/HTTPS"| API
    API --> Common
    API --> Logger
    API --> Auth
    API --> Users
    API --> Admin
    API --> CustomFields
    API --> OTP
    API --> Housekeeping
    API --> UserRoles
    API --> Content

    Auth -->|"OAuth2 Token Validation"| Keycloak
    Users -->|"CRUD & Queries"| Hasura
    Users -->|"Direct ORM"| Postgres
    Admin -->|"CRUD & Management"| Postgres
    CustomFields -->|"CRUD"| Postgres
    OTP -->|"Store & Verify OTP"| Postgres
    Housekeeping -->|"Maintenance Tasks"| Postgres
    UserRoles -->|"Role Management"| Hasura
    Content -->|"Cache & Content CRON"| Hasura

    Hasura -->|"GraphQL/SQL"| Postgres

    Users -.->|"Cron Jobs"| Users
    Content -.->|"Cron Jobs"| Content

    Infra --> API
    Infra --> Postgres

    %% Click Events
    click API "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/main.ts"
    click API "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/app.module.ts"
    click Common "https://github.com/psmri/ubi-beneficiary-backend/tree/main/src/common"
    click Logger "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/logger/logger.service.ts"
    click Auth "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/auth/auth.module.ts"
    click Users "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/users/users.module.ts"
    click Admin "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/admin/admin.module.ts"
    click CustomFields "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/customfields/customfields.module.ts"
    click OTP "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/otp/otp.module.ts"
    click Housekeeping "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/housekeeping/housekeeping.module.ts"
    click UserRoles "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/modules/user_roles/user_roles.module.ts"
    click Content "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/content/content.module.ts"
    click Keycloak "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/services/keycloak/keycloak.module.ts"
    click Hasura "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/services/hasura/hasura.service.ts"
    click Proxy "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/services/proxy/proxy.service.ts"
    click Wallet "https://github.com/psmri/ubi-beneficiary-backend/blob/main/src/services/wallet/wallet.service.ts"
    click Migrations "https://github.com/psmri/ubi-beneficiary-backend/tree/main/migrations/"
    click JSONSchemas "https://github.com/psmri/ubi-beneficiary-backend/tree/main/schemas/credentials/"
    click Infra "https://github.com/psmri/ubi-beneficiary-backend/blob/main/docker-compose.yml"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef external fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef database fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef infra fill:#e0e0e0,stroke:#424242,color:#424242
```
