# rrbanda/mortgage-agents architecture

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

- Interactive diagram: https://gitdiagram.com/rrbanda/mortgage-agents
- Repository: https://github.com/rrbanda/mortgage-agents

## Overview

##### Project type and purpose
- This is a Python-based, AI-driven, full-stack backend system built on LangGraph (an LLM orchestration framework) that implements an end-to-end mortgage application workflow.
- It consists of five specialized “agents” (Application, MortgageAdvisor, Document, Appraisal, Underwriting) that coordinate to intake, guide, verify, value, and underwrite mortgage applications.
- Business rules (200+ rules) live in a Neo4j knowledge graph, and agents dispatch “tools” to perform domain-specific tasks.

##### File structure
- Top level:
- app/agents/… – one folder per agent, each containing an agent.py, prompts.yaml, a tools/ subfolder, and tests/
- app/utils/ – configuration loader, database connection (Neo4j), integrations (file uploads)
- graph.py & langgraph.json – LangGraph orchestration definitions
- deploy/ & mcp/deployment/ & mcp/servers/… – Kubernetes / OpenShift manifests and a standalone credit-check microservice
- Patterns:
- Modular Agent design: each agent = one node in the workflow graph
- Tools library per agent – calls into utils/database (Neo4j), external services (Twilio, file storage) or the mcp credit-check server
- CI/CD & containerization: Containerfile, build.sh, GitHub workflows, Helm/Kustomize

##### README for additional insights
- Workflow sequence: Customer → ApplicationAgent → MortgageAdvisorAgent → DocumentAgent → AppraisalAgent → UnderwritingAgent → Approved/Denied
- Runtime: langgraph dev on port 8123
- Production Observations: professional testing (LangSmith), compliance (Fannie/Freddie), Neo4j KG backend

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Request
    Client["Client / UI"]:::external
    Client -->|"1. Submit Application"| Orchestrator

    %% Orchestrator Layer
    subgraph "Orchestration Layer"
        direction TB
        Orchestrator["LangGraph Orchestrator\n(graph.py + langgraph.json)"]:::orchestration
    end
    click Orchestrator "https://github.com/rrbanda/mortgage-agents/blob/main/app/graph.py"
    click Orchestrator "https://github.com/rrbanda/mortgage-agents/blob/main/app/langgraph.json"

    Orchestrator -->|"2. Route to ApplicationAgent"| ApplicationAgent

    %% Agent Modules
    subgraph "Agent Modules"
        direction TB
        ApplicationAgent["ApplicationAgent\n(prompts.yaml + tools/)"]:::agent
        MortgageAdvisorAgent["MortgageAdvisorAgent\n(prompts.yaml + tools/)"]:::agent
        DocumentAgent["DocumentAgent\n(prompts.yaml + tools/)"]:::agent
        NotificationAgent["NotificationAgent\n(prompts.yaml + tools/)"]:::agent
        AppraisalAgent["AppraisalAgent\n(prompts.yaml + tools/)"]:::agent
        UnderwritingAgent["UnderwritingAgent\n(prompts.yaml + tools/)"]:::agent
    end

    click ApplicationAgent "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/application_agent/agent.py"
    click MortgageAdvisorAgent "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/mortgage_advisor_agent/agent.py"
    click DocumentAgent "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/document_agent/agent.py"
    click NotificationAgent "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/notification_agent/agent.py"
    click AppraisalAgent "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/appraisal_agent/agent.py"
    click UnderwritingAgent "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/underwriting_agent/agent.py"

    ApplicationAgent -->|"3. Completed Application"| MortgageAdvisorAgent
    MortgageAdvisorAgent -->|"4. Advice Provided"| DocumentAgent
    DocumentAgent -->|"5. Docs Verified"| NotificationAgent
    NotificationAgent -->|"5a. SMS via Twilio"| Twilio
    DocumentAgent -->|"5b. Store Files"| FileStorage
    NotificationAgent -->|"6. Notify Applicant"| Orchestrator
    Orchestrator -->|"7. Appraisal Request"| AppraisalAgent
    AppraisalAgent -->|"8. Appraised Value"| UnderwritingAgent
    UnderwritingAgent -->|"9. Underwrite & Credit-check"| mcpCreditServer
    UnderwritingAgent -->|"9a. Credit-check API call"| mcpCreditServer

    UnderwritingAgent -->|"10. Final Decision"| Orchestrator
    Orchestrator -->|"11. Response to Client"| Client

    %% Shared Utilities
    subgraph "Shared Utilities"
        direction TB
        ConfigLoader["Config Loader\n(config.yaml)"]:::external
        Neo4jDB["Neo4j Knowledge Graph\n(business rules)"]:::external
        FileStorage["File Upload Service\n(file_uploads.py)"]:::external
    end
    click ConfigLoader "https://github.com/rrbanda/mortgage-agents/blob/main/app/utils/config.py"
    click Neo4jDB "https://github.com/rrbanda/mortgage-agents/blob/main/app/utils/database.py"
    click Neo4jDB "https://github.com/rrbanda/mortgage-agents/blob/main/app/utils/config.yaml"
    click FileStorage "https://github.com/rrbanda/mortgage-agents/blob/main/app/utils/integrations/file_uploads.py"

    ApplicationAgent -->|"Cypher queries"| Neo4jDB
    MortgageAdvisorAgent -->|"Cypher queries"| Neo4jDB
    DocumentAgent -->|"Cypher queries"| Neo4jDB
    AppraisalAgent -->|"Cypher queries"| Neo4jDB
    UnderwritingAgent -->|"Cypher queries"| Neo4jDB

    %% External Services
    Twilio["Twilio SMS Service"]:::external
    mcpCreditServer["mcp Credit-Check Microservice"]:::external

    click Twilio "https://github.com/rrbanda/mortgage-agents/blob/main/app/agents/notification_agent/tools/send_sms_notification.py"
    click mcpCreditServer "https://github.com/rrbanda/mortgage-agents/blob/main/mcp/servers/credit-check/mcp_credit_server.py"

    %% Deployment Configs
    subgraph "Deployment Configurations"
        direction TB
        K8sManifests["Kubernetes/OpenShift Manifests"]:::external
        MCPDeploy["MCP Microservice Deployment"]:::external
    end
    click K8sManifests "https://github.com/rrbanda/mortgage-agents/blob/main/deploy/deployment.yaml"
    click K8sManifests "https://github.com/rrbanda/mortgage-agents/blob/main/deploy/openshift/openshift-deployment.yaml"
    click K8sManifests "https://github.com/rrbanda/mortgage-agents/blob/main/deploy/configmap.yaml"
    click K8sManifests "https://github.com/rrbanda/mortgage-agents/blob/main/deploy/secret.yaml"
    click MCPDeploy "https://github.com/rrbanda/mortgage-agents/blob/main/mcp/deployment/kubernetes/Containerfile.mcp-server"
    click MCPDeploy "https://github.com/rrbanda/mortgage-agents/blob/main/mcp/deployment/openshift/mcpserver-credit-check.yaml"

    %% Styles
    classDef orchestration fill:#AED6F1,stroke:#1B4F72,stroke-width:1px
    classDef agent fill:#ABEBC6,stroke:#196F3D,stroke-width:1px
    classDef external fill:#F5B041,stroke:#B9770E,stroke-width:1px
```
