# shouqalmaharbah/ibms-app architecture

> Architecture diagram of the GitHub repository shouqalmaharbah/ibms-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shouqalmaharbah/ibms-app
- Repository: https://github.com/shouqalmaharbah/ibms-app

## Overview

IBMS is an insurance brokerage management system, exposed through a Next.js workspace and a NestJS API. The main user workflow spans lead handling, customer onboarding and KYC, needs/risk assessment, recommendation and placement, then servicing and finance; compliance and management capabilities operate alongside it. The tree and README establish these product areas, while excerpts support only a few specific calls, so unsampled module links are omitted rather than inferred.

Main entry points: [`apps/web/lib/auth/api-client.ts`](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/lib/auth/api-client.ts) (API client), [`apps/web/components/lead/LeadPipelineBoard.tsx`](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/components/lead/LeadPipelineBoard.tsx) (Lead pipeline), [`apps/web/app`](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/web/app) (Web application), [`apps/api/src/modules/auth/auth.controller.ts`](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/auth/auth.controller.ts) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_ui["Web application"]
  node_leadboard["Lead pipeline"]
  node_authclient["API client<br/>[api-client.ts]"]
  node_customerui["Customer screen"]
  node_decisionui["Client decision"]
end

subgraph group_foundation["Identity and tenancy"]
  node_authapi["Authentication API<br/>[auth.controller.ts]"]
  node_authlogic["Sessions and MFA<br/>[auth.service.ts]"]
  node_orgctx["Organization context"]
end

subgraph group_acquisition["Customer acquisition"]
  node_lead["Lead management"]
  node_prospect["Prospect management"]
  node_customer["Customer onboarding"]
  node_screening["KYC screening"]
  node_assessment["Needs and risk"]
  node_recommend["Program design"]
end

subgraph group_brokerage["Brokerage operations"]
  node_rfq["Market placement<br/>[rfq.controller.ts]"]
  node_decisionapi["Client decisions"]
  node_policy["Policy lifecycle"]
  node_claims["Claims<br/>[claim.service.ts]"]
  node_finance["Finance"]
  node_crm["CRM"]
  node_crosssell["Cross-sell"]
end

subgraph group_oversight["Compliance and service"]
  node_compliance["Compliance and risk"]
  node_service["Customer service"]
  node_pdpl["Privacy requests<br/>[dsr.controller.ts]"]
  node_audit["Audit trail"]
end

node_broker(("Broker user"))
node_database[("PostgreSQL / Prisma")]

node_broker -->|"uses"| node_ui
node_ui -.->|"requests through"| node_authclient
node_leadboard -->|"transitions via API"| node_lead
node_leadboard -.->|"uses"| node_authclient
node_authclient -->|"calls"| node_authapi
node_authapi -->|"delegates to"| node_authlogic
node_authlogic -->|"adopts organization"| node_orgctx
node_customerui -->|"calls"| node_customer
node_customer -.->|"screening lifecycle"| node_screening
node_decisionui -.->|"loads and records"| node_decisionapi
node_rfq -.->|"serves placement"| node_broker

click node_ui "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/web/app"
click node_leadboard "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/components/lead/LeadPipelineBoard.tsx"
click node_authclient "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/lib/auth/api-client.ts"
click node_authapi "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_authlogic "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/auth/services/auth.service.ts"
click node_orgctx "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/common/org-context/org-context.service.ts"
click node_lead "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/lead"
click node_prospect "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/prospect"
click node_customerui "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/customer/customer.controller.ts"
click node_customer "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/customer/customer.service.ts"
click node_screening "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/customer/screening.service.ts"
click node_assessment "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/needs-assessment"
click node_recommend "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/recommendation"
click node_rfq "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/rfq/rfq.controller.ts"
click node_decisionui "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/components/client-decision/ClientDecisionSection.tsx"
click node_decisionapi "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/client-decision"
click node_policy "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/policy/policy.controller.ts"
click node_claims "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/claim/claim.service.ts"
click node_finance "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/finance"
click node_crm "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/crm"
click node_crosssell "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/cross-sell"
click node_compliance "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/compliance-risk"
click node_service "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/customer-service"
click node_pdpl "https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/pdpl/dsr.controller.ts"
click node_audit "https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/audit-trail"
click node_database "https://github.com/shouqalmaharbah/ibms-app/tree/main/packages/db"

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_ui,node_leadboard,node_authclient,node_customerui,node_decisionui,node_broker toneBlue
class node_authapi,node_authlogic,node_orgctx,node_database toneAmber
class node_lead,node_prospect,node_customer,node_screening,node_assessment,node_recommend toneMint
class node_rfq,node_decisionapi,node_policy,node_claims,node_finance,node_crm,node_crosssell toneRose
class node_compliance,node_service,node_pdpl,node_audit toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/web/app): `apps/web/app`
- [Lead pipeline](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/components/lead/LeadPipelineBoard.tsx): `apps/web/components/lead/LeadPipelineBoard.tsx`
- [API client](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/lib/auth/api-client.ts): `apps/web/lib/auth/api-client.ts`
- [Customer screen](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/customer/customer.controller.ts): `apps/api/src/modules/customer/customer.controller.ts`
- [Client decision](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/web/components/client-decision/ClientDecisionSection.tsx): `apps/web/components/client-decision/ClientDecisionSection.tsx`

### Identity and tenancy

- [Authentication API](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Sessions and MFA](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/auth/services/auth.service.ts): `apps/api/src/modules/auth/services/auth.service.ts`
- [Organization context](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/common/org-context/org-context.service.ts): `apps/api/src/common/org-context/org-context.service.ts`

### Customer acquisition

- [Lead management](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/lead): `apps/api/src/modules/lead`
- [Prospect management](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/prospect): `apps/api/src/modules/prospect`
- [Customer onboarding](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/customer/customer.service.ts): `apps/api/src/modules/customer/customer.service.ts`
- [KYC screening](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/customer/screening.service.ts): `apps/api/src/modules/customer/screening.service.ts`
- [Needs and risk](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/needs-assessment): `apps/api/src/modules/needs-assessment`
- [Program design](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/recommendation): `apps/api/src/modules/recommendation`

### Brokerage operations

- [Market placement](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/rfq/rfq.controller.ts): `apps/api/src/modules/rfq/rfq.controller.ts`
- [Client decisions](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/client-decision): `apps/api/src/modules/client-decision`
- [Policy lifecycle](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/policy/policy.controller.ts): `apps/api/src/modules/policy/policy.controller.ts`
- [Claims](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/claim/claim.service.ts): `apps/api/src/modules/claim/claim.service.ts`
- [Finance](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/finance): `apps/api/src/modules/finance`
- [CRM](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/crm): `apps/api/src/modules/crm`
- [Cross-sell](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/cross-sell): `apps/api/src/modules/cross-sell`

### Compliance and service

- [Compliance and risk](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/compliance-risk): `apps/api/src/modules/compliance-risk`
- [Customer service](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/customer-service): `apps/api/src/modules/customer-service`
- [Privacy requests](https://github.com/shouqalmaharbah/ibms-app/blob/main/apps/api/src/modules/pdpl/dsr.controller.ts): `apps/api/src/modules/pdpl/dsr.controller.ts`
- [Audit trail](https://github.com/shouqalmaharbah/ibms-app/tree/main/apps/api/src/modules/audit-trail): `apps/api/src/modules/audit-trail`

### Other components

- **Broker user**
- [PostgreSQL / Prisma](https://github.com/shouqalmaharbah/ibms-app/tree/main/packages/db): `packages/db`

## Connections

- Broker user → Web application: uses
- Web application → API client: requests through (evidence: `apps/web/app/(app)/retention-disposal/page.tsx`)
- Lead pipeline → Lead management: transitions via API (evidence: `apps/web/components/lead/LeadPipelineBoard.tsx`)
- Lead pipeline → API client: uses (evidence: `apps/web/components/lead/LeadPipelineBoard.tsx`)
- API client → Authentication API: calls (evidence: `apps/web/lib/auth/api-client.ts`)
- Authentication API → Sessions and MFA: delegates to (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Sessions and MFA → Organization context: adopts organization (evidence: `apps/api/src/modules/auth/services/auth.service.ts`)
- Customer screen → Customer onboarding: calls (evidence: `apps/api/src/modules/customer/customer.controller.ts`)
- Customer onboarding → KYC screening: screening lifecycle
- Client decision → Client decisions: loads and records
- Market placement → Broker user: serves placement