# montanogilberto/loanagents_smartloans architecture

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

- Interactive diagram: https://gitdiagram.com/montanogilberto/loanagents_smartloans
- Repository: https://github.com/montanogilberto/loanagents_smartloans

## Overview

SmartLoans is an AI service exposed through FastAPI, with loan negotiation as its documented primary workflow: a borrower or lender messages the assistant, the service uses backend REST data to ground a reply, and the reply returns to the chat. The repository also contains POS support, ticket extraction, identity/evidence validation, and other lending agents. The README documents the negotiation boundary; source-index references reveal additional module dependencies, but unsampled endpoint wiring is not assumed here.

Main entry points: [`main.py`](https://github.com/montanogilberto/loanagents_smartloans/blob/main/main.py) (FastAPI service), [`agents/orchestrator/agent.py`](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/orchestrator/agent.py) (Loan orchestrator), [`agents/pos_clients_support/agent.py`](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_clients_support/agent.py) (POS client support), [`tools/backend_api.py`](https://github.com/montanogilberto/loanagents_smartloans/blob/main/tools/backend_api.py) (Backend REST client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and configuration"]
  node_api["FastAPI service<br/>[main.py]"]
  node_settings["Environment settings<br/>[settings.py]"]
end

subgraph group_lending["Lending agents"]
  node_orchestrator["Loan orchestrator<br/>[agent.py]"]
  node_risk["Risk assessment<br/>[agent.py]"]
  node_recommendation["Loan recommendation<br/>[agent.py]"]
  node_borrower_agent["Borrower perspective<br/>[agent.py]"]
  node_lender_agent["Lender perspective<br/>[agent.py]"]
  node_negotiation["Negotiation reply<br/>[agent.py]"]
  node_contract["Contract preparation<br/>[agent.py]"]
  node_support["Account and legal support<br/>[agent.py]"]
end

subgraph group_pos["POS assistance"]
  node_pos_support["POS client support<br/>[agent.py]"]
  node_pos_income["POS income support<br/>[agent.py]"]
  node_pos_expenses["POS expense support<br/>[agent.py]"]
  node_pos_accounting["POS accounting support<br/>[agent.py]"]
  node_pos_rewards["POS rewards support<br/>[agent.py]"]
end

subgraph group_retrieval["Retrieval and actions"]
  node_retrieval_graph["Graph retrieval<br/>[graph.py]"]
  node_retrieval_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_keyword["Keyword search<br/>[keyword_search.py]"]
  node_semantic["Semantic search<br/>[semantic_search.py]"]
  node_contracts["Action contracts<br/>[contracts.py]"]
  node_pending["Pending actions<br/>[pending_actions.py]"]
end

subgraph group_operations["Business workflows"]
  node_identity["Identity and evidence checks<br/>[agent.py]"]
  node_face["Face validation<br/>[agent.py]"]
  node_evidence["Transfer evidence validation<br/>[agent.py]"]
  node_ticket["Ticket extraction<br/>[proposal.py]"]
  node_matching["Supplier and product matching<br/>[matching.py]"]
  node_reconcile["Ticket reconciliation<br/>[reconcile.py]"]
  node_backend_tools["Backend REST client<br/>[backend_api.py]"]
end

node_user(("Borrower or lender"))
node_backend["SmartLoans backend API"]

node_user -->|"sends message"| node_api
node_api -.->|"runs pipeline"| node_orchestrator
node_orchestrator -->|"runs first"| node_risk
node_orchestrator -->|"runs next"| node_recommendation
node_orchestrator -->|"runs next"| node_borrower_agent
node_orchestrator -->|"runs next"| node_lender_agent
node_orchestrator -->|"synthesizes reply"| node_negotiation
node_api -->|"uses REST client"| node_backend_tools
node_backend_tools -->|"calls REST API"| node_backend
node_api -->|"accepted conversation"| node_contract
node_api -->|"routes support"| node_support
node_api -->|"routes POS support"| node_pos_support
node_pos_support -->|"uses retrieval"| node_retrieval_graph
node_pos_support -->|"uses retrieval"| node_retrieval_hybrid
node_pos_support -->|"uses backend tools"| node_backend_tools
node_pos_support -->|"proposes actions"| node_pending
node_semantic -->|"fetches documents"| node_keyword
node_keyword -->|"fetches OpenAPI"| node_backend
node_pending -->|"uses contracts"| node_contracts
node_ticket -->|"matches records"| node_matching
node_api -.->|"handles validation"| node_identity
node_api -.->|"handles validation"| node_face
node_api -.->|"handles validation"| node_evidence
node_api -.->|"handles extraction"| node_ticket

click node_api "https://github.com/montanogilberto/loanagents_smartloans/blob/main/main.py"
click node_settings "https://github.com/montanogilberto/loanagents_smartloans/blob/main/config/settings.py"
click node_orchestrator "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/orchestrator/agent.py"
click node_risk "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/risk/agent.py"
click node_recommendation "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/recommendation/agent.py"
click node_borrower_agent "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/borrower/agent.py"
click node_lender_agent "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/lender/agent.py"
click node_negotiation "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/negotiation/agent.py"
click node_contract "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/contract/agent.py"
click node_support "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/support/agent.py"
click node_identity "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/id_document/agent.py"
click node_face "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/face_validation/agent.py"
click node_evidence "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/evidence_validation/agent.py"
click node_ticket "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/ticket_extraction/proposal.py"
click node_matching "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/ticket_extraction/matching.py"
click node_reconcile "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/ticket_extraction/reconcile.py"
click node_pos_support "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_clients_support/agent.py"
click node_pos_income "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_income_support/agent.py"
click node_pos_expenses "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_expenses_support/agent.py"
click node_pos_accounting "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_accounting_support/agent.py"
click node_pos_rewards "https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_rewards_support/agent.py"
click node_retrieval_graph "https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/graph.py"
click node_retrieval_hybrid "https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/hybrid.py"
click node_keyword "https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/keyword_search.py"
click node_semantic "https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/semantic_search.py"
click node_contracts "https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/contracts.py"
click node_pending "https://github.com/montanogilberto/loanagents_smartloans/blob/main/tools/pending_actions.py"
click node_backend_tools "https://github.com/montanogilberto/loanagents_smartloans/blob/main/tools/backend_api.py"

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_api,node_settings toneBlue
class node_orchestrator,node_risk,node_recommendation,node_borrower_agent,node_lender_agent,node_negotiation,node_contract,node_support toneAmber
class node_pos_support,node_pos_income,node_pos_expenses,node_pos_accounting,node_pos_rewards,node_backend toneMint
class node_retrieval_graph,node_retrieval_hybrid,node_keyword,node_semantic,node_contracts,node_pending toneRose
class node_identity,node_face,node_evidence,node_ticket,node_matching,node_reconcile,node_backend_tools,node_user toneIndigo
```

## Components

### API and configuration

- [FastAPI service](https://github.com/montanogilberto/loanagents_smartloans/blob/main/main.py): `main.py`
- [Environment settings](https://github.com/montanogilberto/loanagents_smartloans/blob/main/config/settings.py): `config/settings.py`

### Lending agents

- [Loan orchestrator](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/orchestrator/agent.py): `agents/orchestrator/agent.py`
- [Risk assessment](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/risk/agent.py): `agents/risk/agent.py`
- [Loan recommendation](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/recommendation/agent.py): `agents/recommendation/agent.py`
- [Borrower perspective](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/borrower/agent.py): `agents/borrower/agent.py`
- [Lender perspective](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/lender/agent.py): `agents/lender/agent.py`
- [Negotiation reply](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/negotiation/agent.py): `agents/negotiation/agent.py`
- [Contract preparation](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/contract/agent.py): `agents/contract/agent.py`
- [Account and legal support](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/support/agent.py): `agents/support/agent.py`

### POS assistance

- [POS client support](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_clients_support/agent.py): `agents/pos_clients_support/agent.py`
- [POS income support](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_income_support/agent.py): `agents/pos_income_support/agent.py`
- [POS expense support](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_expenses_support/agent.py): `agents/pos_expenses_support/agent.py`
- [POS accounting support](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_accounting_support/agent.py): `agents/pos_accounting_support/agent.py`
- [POS rewards support](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/pos_rewards_support/agent.py): `agents/pos_rewards_support/agent.py`

### Retrieval and actions

- [Graph retrieval](https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/graph.py): `retrieval/graph.py`
- [Hybrid retrieval](https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/hybrid.py): `retrieval/hybrid.py`
- [Keyword search](https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/keyword_search.py): `retrieval/keyword_search.py`
- [Semantic search](https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/semantic_search.py): `retrieval/semantic_search.py`
- [Action contracts](https://github.com/montanogilberto/loanagents_smartloans/blob/main/retrieval/contracts.py): `retrieval/contracts.py`
- [Pending actions](https://github.com/montanogilberto/loanagents_smartloans/blob/main/tools/pending_actions.py): `tools/pending_actions.py`

### Business workflows

- [Identity and evidence checks](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/id_document/agent.py): `agents/id_document/agent.py`
- [Face validation](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/face_validation/agent.py): `agents/face_validation/agent.py`
- [Transfer evidence validation](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/evidence_validation/agent.py): `agents/evidence_validation/agent.py`
- [Ticket extraction](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/ticket_extraction/proposal.py): `agents/ticket_extraction/proposal.py`
- [Supplier and product matching](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/ticket_extraction/matching.py): `agents/ticket_extraction/matching.py`
- [Ticket reconciliation](https://github.com/montanogilberto/loanagents_smartloans/blob/main/agents/ticket_extraction/reconcile.py): `agents/ticket_extraction/reconcile.py`
- [Backend REST client](https://github.com/montanogilberto/loanagents_smartloans/blob/main/tools/backend_api.py): `tools/backend_api.py`

### Other components

- **Borrower or lender**
- **SmartLoans backend API**

## Connections

- Borrower or lender → FastAPI service: sends message (evidence: `README.md`)
- FastAPI service → Loan orchestrator: runs pipeline
- Loan orchestrator → Risk assessment: runs first (evidence: `agents/orchestrator/agent.py`)
- Loan orchestrator → Loan recommendation: runs next (evidence: `agents/orchestrator/agent.py`)
- Loan orchestrator → Borrower perspective: runs next (evidence: `agents/orchestrator/agent.py`)
- Loan orchestrator → Lender perspective: runs next (evidence: `agents/orchestrator/agent.py`)
- Loan orchestrator → Negotiation reply: synthesizes reply (evidence: `agents/orchestrator/agent.py`)
- FastAPI service → Backend REST client: uses REST client (evidence: `main.py`)
- Backend REST client → SmartLoans backend API: calls REST API (evidence: `README.md`)
- FastAPI service → Contract preparation: accepted conversation (evidence: `main.py`)
- FastAPI service → Account and legal support: routes support (evidence: `main.py`)
- FastAPI service → POS client support: routes POS support (evidence: `main.py`)
- POS client support → Graph retrieval: uses retrieval (evidence: `agents/pos_clients_support/agent.py`)
- POS client support → Hybrid retrieval: uses retrieval (evidence: `agents/pos_clients_support/agent.py`)
- POS client support → Backend REST client: uses backend tools (evidence: `agents/pos_clients_support/agent.py`)
- POS client support → Pending actions: proposes actions (evidence: `agents/pos_clients_support/agent.py`)
- Semantic search → Keyword search: fetches documents (evidence: `retrieval/semantic_search.py`)
- Keyword search → SmartLoans backend API: fetches OpenAPI (evidence: `retrieval/keyword_search.py`)
- Pending actions → Action contracts: uses contracts (evidence: `tools/pending_actions.py`)
- Ticket extraction → Supplier and product matching: matches records (evidence: `agents/ticket_extraction/proposal.py`)
- FastAPI service → Identity and evidence checks: handles validation
- FastAPI service → Face validation: handles validation
- FastAPI service → Transfer evidence validation: handles validation
- FastAPI service → Ticket extraction: handles extraction (evidence: `main.py`)
