flowchart TB

subgraph USERS["End Users / Clients"]
direction TB
U1["Claude Desktop"]
U2["Cursor IDE"]
U3["Loan Officer UI"]
U4["Founder Dashboard"]
end

subgraph CLIENT["MCP Client"]
direction TB
Q["Natural Language Request"]
end

subgraph SERVER["Alternative Credit Intelligence MCP Server"]
direction TB
T1["Analyze Creditworthiness"]
T2["Analyze Financial Behavior"]
T3["Generate Underwriting Report"]
end

subgraph GRAPH["LangGraph Multi-Agent Workflow"]

direction TB

Loader["User Context Loader"]

Transaction["Transaction Agent"]

Savings["Savings Agent"]

Behavior["Behavior Agent"]

Risk["Risk Agent"]

Decision["Credit Decision Agent"]

Explanation["Explanation Agent"]

Loader --> Transaction
Loader --> Savings

Transaction --> Behavior
Savings --> Behavior

Behavior --> Risk

Risk --> Decision

Decision --> Explanation

end

subgraph API["Express Backend"]

direction TB

Controllers["Controllers"]

Services["Services"]

Repositories["Repositories"]

end

subgraph DATABASE["PostgreSQL"]

direction TB

Users["users"]

Transactions["transactions"]

SavingsTable["savings_history"]

Reports["underwriting_reports"]

Audit["audit_logs"]

end

USERS --> CLIENT

CLIENT --> SERVER

SERVER --> GRAPH

GRAPH --> API

API --> DATABASE

DATABASE --> SERVER

flowchart LR
    IN(["User ID"]) --> UA["assertUserExists()"]

    UA -->|found| TA["TransactionService\nLast 6 months data"]
    UA -->|not found| ERR(["isError: true\nUser not found"])

    TA --> TX["Transaction Summary\ntotalTransactions\nfailedTransactions\nmonthlyInflow/Outflow\nincomeConsistencyScore"]

    IN --> SA["SavingsService\nAll history"]
    SA --> SV["Savings Summary\ntotalDeposits/Withdrawals\ncurrentBalance\ndepositCount"]

    TX --> S1["Transaction\nConsistency Score\nx 0.35"]
    SV --> S2["Savings\nDiscipline Score\nx 0.40"]
    TX --> S3["Cashflow\nStability Score\nx 0.25"]

    S1 --> WA["Weighted\nOverall Score\n0 to 100"]
    S2 --> WA
    S3 --> WA

    WA --> CS["Credit Score\nplus/minus adjustments\nfor bonuses/penalties"]

    CS --> RISK["Risk Level\n70+ = LOW\n40-69 = MEDIUM\nbelow 40 = HIGH"]

    RISK --> DEC["Decision\nLOW+60 = APPROVED\nMEDIUM+40 = REVIEW\nelse = REJECTED"]

    DEC --> AMT["Recommended Amount\nLOW x 0.7\nMEDIUM x 0.5\nHIGH x 0.2"]

    DEC --> OUT(["Underwriting Report\nSaved to DB"])
    RISK --> OUT
    AMT --> OUT

Credit Score = (Transaction Consistency × 0.35)
             + (Savings Discipline     × 0.40)
             + (Cashflow Stability     × 0.25)

erDiagram
    users {
        UUID id PK
        VARCHAR name
        VARCHAR phone UK
        VARCHAR occupation
        VARCHAR employer_name
        DECIMAL monthly_income
        TIMESTAMP created_at
        TIMESTAMP updated_at
    }

    transactions {
        UUID id PK
        UUID user_id FK
        DECIMAL amount
        VARCHAR type
        VARCHAR status
        VARCHAR category
        TEXT description
        TIMESTAMP timestamp
    }

    savings_history {
        UUID id PK
        UUID user_id FK
        DECIMAL deposit_amount
        DECIMAL withdrawal_amount
        DECIMAL balance
        TIMESTAMP created_at
    }

    underwriting_reports {
        UUID id PK
        UUID user_id FK
        INTEGER credit_score
        VARCHAR risk_level
        DECIMAL recommended_amount
        VARCHAR recommendation
        TEXT explanation
        JSONB details
        TIMESTAMP created_at
    }

    audit_logs {
        UUID id PK
        UUID user_id FK
        VARCHAR action
        VARCHAR resource
        JSONB details
        VARCHAR ip_address
        TIMESTAMP created_at
    }

    users ||--o{ transactions : "has"
    users ||--o{ savings_history : "has"
    users ||--o{ underwriting_reports : "has"
    users ||--o{ audit_logs : "has"

graph TB
    subgraph DEV["Local Development"]
        CODE["Source Code"]
        CSV["CSV Datasets\nusers · transactions · savings"]
        SEED["npm run seed"]
    end

    subgraph GH["GitHub"]
        REPO["Ppp111ppp111/LoanRiskLens_MCP\nbranch: main"]
    end

    subgraph RENDER["Render.com"]
        SVC1["altcredit-apis\nNode.js · PORT 3000\nnpm run dev"]
        SVC2["altcredit-mcp\nNode.js · PORT 3001\nnpm run dev:mcp"]
    end

    subgraph SUPABASE["Supabase"]
        PG["PostgreSQL\naws-ap-southeast-1\nConnection Pooling"]
    end

    CODE -- "git push" --> REPO
    REPO -- "Auto Deploy" --> SVC1
    REPO -- "Auto Deploy" --> SVC2
    SVC1 -- "DATABASE_URL" --> PG
    SVC2 -- "DATABASE_URL" --> PG
    CSV --> SEED
    SEED -- "upsert" --> PG

{
  "mcpServers": {
    "LoanRiskLens": {
      "url": "https://altcredit-mcp.onrender.com/mcp"
    }
  }
}

Analyze the creditworthiness of user 550e8400-e29b-41d4-a716-446655440001

Generate a full underwriting report for user ID 550e8400-e29b-41d4-a716-446655440001

Check the financial behavior profile of user 85919b78-ec7d-4d17-8e67-6a02ebfca84a

# 1. Clone and install
git clone https://github.com/Ppp111ppp111/LoanRiskLens_MCP.git
cd LoanRiskLens_MCP
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env — set DB_HOST, DB_NAME, DB_USER, DB_PASSWORD

# 3. Initialize schema and seed demo data
npm run seed

# 4. Start API server (port 3000)
npm run dev

# 5. Start MCP server (port 3001, separate terminal)
npm run dev:mcp

# 6. Run tests
npm test

LoanRiskLens_MCP/
├── apps/
│   └── api/                    # Express REST API (port 3000)
│       ├── src/controllers/    # Route handlers
│       ├── src/services/       # Business logic (creditService, etc.)
│       ├── src/repositories/   # DB access layer
│       └── src/middleware/     # Auth, security, error handling
├── packages/
│   └── mcp-server/             # HTTP JSON-RPC MCP Server (port 3001)
│       ├── src/server/         # mcpServer.js — JSON-RPC router
│       └── src/tools/          # creditTools.js — tool definitions
├── credit-engine/              # Pure scoring & analysis logic
│   ├── src/scoring/            # Score calculators
│   └── src/analysis/           # Risk classifier, profile analyzer
├── langgraph-workflows/        # 6-agent sequential workflow
│   ├── src/agents/             # Individual agent classes
│   └── src/workflows/          # CreditIntelligenceWorkflow
├── shared/                     # Common modules
│   ├── src/config/             # App configuration
│   ├── src/database/           # pg Pool + schema init
│   └── src/utils/              # helpers, logger, validator
├── scripts/
│   └── seed-datasets.js        # CSV → PostgreSQL seed script
└── docs/                       # Documentation