eHub — Architecture¶

All facts derived from source code in apps/, libs/, nest-cli.json, package.json, docker-compose.yml, .env.example. Sections marked ⚠ flag known ambiguities.

Tech Stack¶

Monorepo Layout¶

pencom-project/
├── apps/                    # 8 NestJS applications
│   ├── api-gateway/         # Public HTTP entry, JWT auth, routes to backend
│   ├── core/                # Employer/employee/auth domain, Oracle PENCOM bridge
│   ├── payments/            # Remita integration, payment state, certificate fees
│   ├── compliance/          # Contributions, penalties, PCC/GLI workflows, reports
│   ├── notifications/       # SendGrid + Termii fan-out, Mongo audit
│   ├── external-integrations/ # CAC company records + PFC partner credentials
│   ├── external-gateway/    # Partner-facing HTTP API — partner auth + CSV upload ingress
│   └── audit/               # Append-only audit-log API (Postgres)
├── libs/                    # Internal shared libraries
│   ├── shared/              # Guards, decorators, DTOs, PencomInternalHttpClient, FileUploadService
│   ├── shared/database-job-status/  # JobStatus + FailedBatch entities
│   ├── database/            # BaseEntity, BaseTypeOrmRepository, DatabaseModule
│   ├── url-config/          # Typed accessor over *_SERVICE_URL env vars
│   └── logger/              # LoggerModule.forRoot wrapper
├── monitoring/ansible/      # Prometheus + Grafana + node-exporter Ansible roles
├── .github/workflows/       # deploy-prod, deploy-staging, deploy-monitoring
├── nest-cli.json            # Monorepo project definitions
└── scripts/migration.js     # Interactive TypeORM CLI driver for per-app migrations

Services and Ports¶

Process Topology (Request Flow)¶

┌───────────────┐                              ┌────────────────────┐
│  Web client   │  HTTPS                       │ External partner   │
│ (employer /   │ ──────────────┐              │ (PFC)              │
│  admin)       │               ▼              └──────────┬─────────┘
└───────────────┘     ┌──────────────────┐               │ Bearer JWT
                      │   api-gateway    │     ┌──────────▼─────────┐
                      │  JwtAuthGuard    │     │  external-gateway  │
                      │  ValidationPipe  │     │  ExternalTokenAuth │
                      │  Swagger, CORS   │     └──────────┬─────────┘
                      └─────────┬────────┘               │
                                │  HTTP (x-internal-api-key)       │
        ┌───────────────────────┼──────────────────────────────────┘
        │              ┌────────┼────────────────┐
        ▼              ▼        ▼                ▼
   ┌─────────┐  ┌────────────┐ ┌──────────┐  ┌──────────┐
   │  core   │  │ compliance │ │ payments │  │  audit   │
   └─┬───────┘  └─────┬──────┘ └──────────┘  └──────────┘
     │                │ HTTP + Bull queue (Redis)
     ▼                ▼
  Postgres      ┌──────────────┐         ┌───────────────────┐
  + Oracle  ────│ notifications│────────▶│ SendGrid / Termii │
  + Mongo        └──────────────┘         └───────────────────┘

Key points:

• All synchronous inter-service calls are HTTP, not TCP, despite message-pattern enum names suggesting otherwise. The enums like CoreMessagePatterns.REGISTER_EMPLOYER are used as HTTP path strings.
• No central message bus. No Kafka or RabbitMQ. Redis/Bull is used only for file-processing jobs and outbound webhooks.
• notifications self-emits over in-process TCP for fire-and-forget email dispatch (HTTP 202 → in-process TCP EventPattern → SendGrid). ⚠ A crash between the 202 and the handler loses the email.
• compliance runs scheduled jobs: certificate expiry (hourly), GLI expiry (midnight), employer revaluation (midnight), approved evaluation re-sync (hourly), grace-period notifications (1am). Bull processors for PFC uploads also run here.

Auth Model¶

Three independent authentication boundaries:

1. End-user JWT (JWT_SECRET)¶

• 1h access token; 7d refresh token on path: /auth.
• Issued by api-gateway AuthController (employer) and AdminAuthController (admin) after OTP verification.
• Verified by global JwtAuthGuard on api-gateway only, via JwtStrategy.
• Cookie first (access_token, httpOnly), then Authorization: Bearer.
• Opt-out per route with @Public().

2. Internal API key (INTERNAL_API_KEY)¶

• Header: x-internal-api-key.
• Backend services (core, notifications, audit) register ApiKeyAuthGuard globally.
• ⚠ compliance, payments, and external-integrations do NOT register it — rely on network isolation.
• PencomInternalHttpClient automatically attaches this header to every outbound call.

3. External partner JWT (EXTERNAL_JWT_SECRET)¶

• 1h expiry; issued by external-integrations PartnerController.getToken.
• Verified by ExternalTokenAuthGuard on external-gateway.
• JWT payload embeds the full partner {id, name, code, organizationType} — no per-request DB lookup.

Admin RBAC on top of JWT¶

• RolesGuard + @Roles(AdminRole.SUPER_ADMIN) for super-admin-only endpoints.
• JourneyPermissionsGuard + @RequireJourney([journeys], role?) for fine-grained access. SUPER_ADMIN bypasses. Nine journey codes: GLI, PCC, EMPLOYEE_MANAGEMENT, PAYMENT_MANAGEMENT, HELP_AND_SUPPORT, four EMPLOYER_CODE_REQUEST_* variants.

Data Strategy¶

• PostgreSQL per service. synchronize: false, autoLoadEntities: true, migrationsRun: true. Migrations run from compiled JS in dist/.../migrations/ at boot.
• Standalone CLI config. apps/<app>/src/typeorm.config.ts drives yarn gen:migration. It lists entities explicitly — newly created entities missing from this file will produce empty migrations.
• Cross-DB access from compliance. Compliance opens a second named connection EXTERNAL_INTEGRATIONS_DB to read IntegrationPartner records. It also cross-app imports PencomModule from core, opening its own Oracle connection pool — meaning compliance must have all PENCOM_DB_* env vars set.
• Soft deletes via @DeleteDateColumn deletedAt on BaseEntity.
• JSONB columns for fast-changing compliance aggregates, metadata, and webhook payloads.
• Natural-key deduplication in contribution ingest. The key for employee_monthly_contributions is (employer_code, rsa_pin, date_of_contribution, value_date, contribution_type), enforced as a partial unique index.
• Oracle is read-only. No INSERT/UPDATE/DELETE against Oracle anywhere in the codebase. Every Oracle call is user-triggered, not scheduled.

CI/CD¶

Each app has its own Dockerfile at apps/<app>/Dockerfile. Only changed apps are rebuilt per deployment.

Cross-Cutting Concerns¶

Known Ambiguities¶

1. TCP transports declared but unused in api-gateway and payments.
2. compliance registers core entities in TypeOrmModule.forFeature — either the compliance DB has those tables or it's dead code.
3. notifications self-emit is non-durable — crash between HTTP 202 and TCP handler loses the email.
4. audit.service.ts:39-57 drops derived fields before insert; entity_type NOT NULL violation likely.
5. Several admin endpoints lack guards in compliance and payments — protected only at the gateway layer.
6. Hard-coded values: Convenience Fee ₦161.25 (payments), grace days 11 in live penalty path.
7. SPACES_* env vars missing from .env.example despite being required by FileUploadService.
8. payments CLI reads PAYMENTS_DB_* (plural) but runtime reads PAYMENT_DB_* — set both.
9. AUTH_PILOT_ALLOWLIST gates all logins but is undocumented in .env.example.
10. MySQL not integrated — mysql2 installed but no connection, entity, or query exists.