# faelsou/settlr architecture

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

- Interactive diagram: https://gitdiagram.com/faelsou/settlr
- Repository: https://github.com/faelsou/settlr

## Overview

Settlr is a WhatsApp collections agent paired with deterministic payment reconciliation and a human-operator dashboard. The main workflow receives debtor messages or payment evidence, routes conversational work through policy-guarded agent tasks, and processes receipts or bank-reported payments through matching and reconciliation; operators review exceptions and approvals in the panel. Separate branches cover scheduled collections, issuer ingestion, onboarding, and Slack-based AIOps. Edges follow explicit README statements or shown imports/calls; some capabilities are documented but their internal wiring was not sampled.

Main entry points: [`api/app/channels/tasks.py`](https://github.com/faelsou/settlr/blob/main/api/app/channels/tasks.py) (Message routing), [`api/app/api/routes/webhooks.py`](https://github.com/faelsou/settlr/blob/main/api/app/api/routes/webhooks.py) (Inbound webhooks), [`api/app/reconciliation/service.py`](https://github.com/faelsou/settlr/blob/main/api/app/reconciliation/service.py) (Reconciliation), [`api/app/aiops/engine.py`](https://github.com/faelsou/settlr/blob/main/api/app/aiops/engine.py) (AIOps engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["WhatsApp and agent"]
  node_webhook["Inbound webhooks<br/>[webhooks.py]"]
  node_wa["WhatsApp channel<br/>[whatsapp.py]"]
  node_inbound["Message routing<br/>[tasks.py]"]
  node_agent["Agent turns<br/>[tasks.py]"]
  node_outbound["Outbound delivery<br/>[outbound.py]"]
  node_delivery["Delivery tracking<br/>[delivery.py]"]
  node_channelmetrics["Channel metrics<br/>[metrics.py]"]
end

subgraph group_collections["Collections and onboarding"]
  node_dunning["Collection rules<br/>[official.py]"]
  node_dunningservice["Dunning service<br/>[service.py]"]
  node_onboarding["Member onboarding"]
end

subgraph group_payments["Payments and reconciliation"]
  node_receipt["Receipt processing<br/>[service.py]"]
  node_bankingest["Bank ingestion<br/>[tasks.py]"]
  node_reconciliation["Reconciliation<br/>[service.py]"]
  node_matcher["Payment matcher<br/>[matcher.py]"]
  node_records[("Business records<br/>[entities.py]")]
  node_workers["Task workers<br/>[celery_app.py]"]
end

subgraph group_operations["Operator panel"]
  node_dashboard["Operator dashboard"]
  node_gateway["API gateway<br/>[gateway.py]"]
  node_audit[("Audit log<br/>[audit.py]")]
end

subgraph group_aiops["Incident response"]
  node_aiops["AIOps engine<br/>[engine.py]"]
  node_diagnosis["Incident diagnosis<br/>[diagnose.py]"]
  node_slack["Slack notifications<br/>[slack.py]"]
  node_incidentstore[("Incident store<br/>[store.py]")]
end

node_debtor(("Debtor"))
node_operator(("Operator"))
node_bank{{"Bank and issuers"}}
node_evolution{{"Evolution API"}}
node_slackservice{{"Slack"}}
node_alertmanager{{"Alertmanager"}}

node_debtor -->|"sends messages"| node_evolution
node_evolution -->|"posts events"| node_webhook
node_webhook -->|"parses events"| node_wa
node_webhook -->|"queues inbound"| node_inbound
node_inbound -->|"queues agent turn"| node_agent
node_inbound -->|"queues receipt"| node_receipt
node_agent -->|"sends replies"| node_outbound
node_outbound -->|"dispatches messages"| node_delivery
node_delivery -->|"sends via channel"| node_wa
node_wa -->|"uses API"| node_evolution
node_inbound -->|"records routing"| node_channelmetrics
node_dunningservice -->|"applies rules"| node_dunning
node_dunningservice -->|"sends collections"| node_outbound
node_operator -->|"reviews work"| node_dashboard
node_dashboard -->|"calls API"| node_gateway
node_gateway -->|"audits actions"| node_audit
node_receipt -->|"records payment"| node_records
node_receipt -->|"requests match"| node_matcher
node_bank -->|"sends payment data"| node_bankingest
node_bankingest -->|"queues reconciliation"| node_reconciliation
node_reconciliation -->|"scores candidates"| node_matcher
node_reconciliation -->|"updates payment state"| node_records
node_reconciliation -->|"queues settlement"| node_bankingest
node_webhook -->|"queues issuer events"| node_bankingest
node_inbound -->|"dispatches tasks"| node_workers
node_onboarding -.->|"manages members"| node_records
node_alertmanager -->|"reports alerts"| node_aiops
node_aiops -->|"collects evidence"| node_diagnosis
node_aiops -->|"posts incident"| node_slack
node_slack -->|"notifies operators"| node_slackservice
node_aiops -.->|"tracks incidents"| node_incidentstore

click node_webhook "https://github.com/faelsou/settlr/blob/main/api/app/api/routes/webhooks.py"
click node_wa "https://github.com/faelsou/settlr/blob/main/api/app/channels/whatsapp.py"
click node_inbound "https://github.com/faelsou/settlr/blob/main/api/app/channels/tasks.py"
click node_agent "https://github.com/faelsou/settlr/blob/main/api/app/agent/tasks.py"
click node_outbound "https://github.com/faelsou/settlr/blob/main/api/app/channels/outbound.py"
click node_delivery "https://github.com/faelsou/settlr/blob/main/api/app/channels/delivery.py"
click node_channelmetrics "https://github.com/faelsou/settlr/blob/main/api/app/channels/metrics.py"
click node_dunning "https://github.com/faelsou/settlr/blob/main/api/app/dunning/official.py"
click node_dunningservice "https://github.com/faelsou/settlr/blob/main/api/app/dunning/service.py"
click node_onboarding "https://github.com/faelsou/settlr/tree/main/api/app/onboarding"
click node_receipt "https://github.com/faelsou/settlr/blob/main/api/app/receipts/service.py"
click node_bankingest "https://github.com/faelsou/settlr/blob/main/api/app/ingest/tasks.py"
click node_reconciliation "https://github.com/faelsou/settlr/blob/main/api/app/reconciliation/service.py"
click node_matcher "https://github.com/faelsou/settlr/blob/main/api/app/reconciliation/matcher.py"
click node_records "https://github.com/faelsou/settlr/blob/main/api/app/models/entities.py"
click node_workers "https://github.com/faelsou/settlr/blob/main/api/app/workers/celery_app.py"
click node_dashboard "https://github.com/faelsou/settlr/tree/main/web/app/(painel)"
click node_gateway "https://github.com/faelsou/settlr/blob/main/api/app/services/gateway.py"
click node_audit "https://github.com/faelsou/settlr/blob/main/api/app/core/audit.py"
click node_aiops "https://github.com/faelsou/settlr/blob/main/api/app/aiops/engine.py"
click node_diagnosis "https://github.com/faelsou/settlr/blob/main/api/app/aiops/diagnose.py"
click node_slack "https://github.com/faelsou/settlr/blob/main/api/app/aiops/slack.py"
click node_incidentstore "https://github.com/faelsou/settlr/blob/main/api/app/aiops/store.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_webhook,node_wa,node_inbound,node_agent,node_outbound,node_delivery,node_channelmetrics toneBlue
class node_dunning,node_dunningservice,node_onboarding toneAmber
class node_receipt,node_bankingest,node_reconciliation,node_matcher,node_records,node_workers,node_evolution toneMint
class node_dashboard,node_gateway,node_audit toneRose
class node_aiops,node_diagnosis,node_slack,node_incidentstore,node_debtor,node_operator,node_bank,node_slackservice,node_alertmanager toneIndigo
```

## Components

### WhatsApp and agent

- [Inbound webhooks](https://github.com/faelsou/settlr/blob/main/api/app/api/routes/webhooks.py): `api/app/api/routes/webhooks.py`
- [WhatsApp channel](https://github.com/faelsou/settlr/blob/main/api/app/channels/whatsapp.py): `api/app/channels/whatsapp.py`
- [Message routing](https://github.com/faelsou/settlr/blob/main/api/app/channels/tasks.py): `api/app/channels/tasks.py`
- [Agent turns](https://github.com/faelsou/settlr/blob/main/api/app/agent/tasks.py): `api/app/agent/tasks.py`
- [Outbound delivery](https://github.com/faelsou/settlr/blob/main/api/app/channels/outbound.py): `api/app/channels/outbound.py`
- [Delivery tracking](https://github.com/faelsou/settlr/blob/main/api/app/channels/delivery.py): `api/app/channels/delivery.py`
- [Channel metrics](https://github.com/faelsou/settlr/blob/main/api/app/channels/metrics.py): `api/app/channels/metrics.py`

### Collections and onboarding

- [Collection rules](https://github.com/faelsou/settlr/blob/main/api/app/dunning/official.py): `api/app/dunning/official.py`
- [Dunning service](https://github.com/faelsou/settlr/blob/main/api/app/dunning/service.py): `api/app/dunning/service.py`
- [Member onboarding](https://github.com/faelsou/settlr/tree/main/api/app/onboarding): `api/app/onboarding`

### Payments and reconciliation

- [Receipt processing](https://github.com/faelsou/settlr/blob/main/api/app/receipts/service.py): `api/app/receipts/service.py`
- [Bank ingestion](https://github.com/faelsou/settlr/blob/main/api/app/ingest/tasks.py): `api/app/ingest/tasks.py`
- [Reconciliation](https://github.com/faelsou/settlr/blob/main/api/app/reconciliation/service.py): `api/app/reconciliation/service.py`
- [Payment matcher](https://github.com/faelsou/settlr/blob/main/api/app/reconciliation/matcher.py): `api/app/reconciliation/matcher.py`
- [Business records](https://github.com/faelsou/settlr/blob/main/api/app/models/entities.py): `api/app/models/entities.py`
- [Task workers](https://github.com/faelsou/settlr/blob/main/api/app/workers/celery_app.py): `api/app/workers/celery_app.py`

### Operator panel

- [Operator dashboard](https://github.com/faelsou/settlr/tree/main/web/app/(painel)): `web/app/(painel)`
- [API gateway](https://github.com/faelsou/settlr/blob/main/api/app/services/gateway.py): `api/app/services/gateway.py`
- [Audit log](https://github.com/faelsou/settlr/blob/main/api/app/core/audit.py): `api/app/core/audit.py`

### Incident response

- [AIOps engine](https://github.com/faelsou/settlr/blob/main/api/app/aiops/engine.py): `api/app/aiops/engine.py`
- [Incident diagnosis](https://github.com/faelsou/settlr/blob/main/api/app/aiops/diagnose.py): `api/app/aiops/diagnose.py`
- [Slack notifications](https://github.com/faelsou/settlr/blob/main/api/app/aiops/slack.py): `api/app/aiops/slack.py`
- [Incident store](https://github.com/faelsou/settlr/blob/main/api/app/aiops/store.py): `api/app/aiops/store.py`

### Other components

- **Debtor**
- **Operator**
- **Bank and issuers**
- **Evolution API**
- **Slack**
- **Alertmanager**

## Connections

- Debtor → Evolution API: sends messages (evidence: `README.md`)
- Evolution API → Inbound webhooks: posts events (evidence: `api/app/api/routes/webhooks.py`)
- Inbound webhooks → WhatsApp channel: parses events (evidence: `api/app/api/routes/webhooks.py`)
- Inbound webhooks → Message routing: queues inbound (evidence: `api/app/api/routes/webhooks.py`)
- Message routing → Agent turns: queues agent turn (evidence: `api/app/channels/tasks.py`)
- Message routing → Receipt processing: queues receipt (evidence: `api/app/channels/tasks.py`)
- Agent turns → Outbound delivery: sends replies (evidence: `api/app/agent/tasks.py`)
- Outbound delivery → Delivery tracking: dispatches messages (evidence: `api/app/channels/outbound.py`)
- Delivery tracking → WhatsApp channel: sends via channel (evidence: `api/app/channels/delivery.py`)
- WhatsApp channel → Evolution API: uses API (evidence: `api/app/channels/whatsapp.py`)
- Message routing → Channel metrics: records routing (evidence: `api/app/channels/tasks.py`)
- Dunning service → Collection rules: applies rules (evidence: `api/app/dunning/service.py`)
- Dunning service → Outbound delivery: sends collections (evidence: `api/app/dunning/service.py`)
- Operator → Operator dashboard: reviews work (evidence: `README.md`)
- Operator dashboard → API gateway: calls API (evidence: `README.md`)
- API gateway → Audit log: audits actions (evidence: `README.md`)
- Receipt processing → Business records: records payment (evidence: `api/app/receipts/service.py`)
- Receipt processing → Payment matcher: requests match (evidence: `api/app/receipts/service.py`)
- Bank and issuers → Bank ingestion: sends payment data (evidence: `README.md`)
- Bank ingestion → Reconciliation: queues reconciliation (evidence: `api/app/ingest/tasks.py`)
- Reconciliation → Payment matcher: scores candidates (evidence: `api/app/reconciliation/service.py`)
- Reconciliation → Business records: updates payment state (evidence: `api/app/reconciliation/service.py`)
- Reconciliation → Bank ingestion: queues settlement (evidence: `api/app/reconciliation/service.py`)
- Inbound webhooks → Bank ingestion: queues issuer events (evidence: `api/app/api/routes/webhooks.py`)
- Message routing → Task workers: dispatches tasks (evidence: `api/app/channels/tasks.py`)
- Member onboarding → Business records: manages members
- Alertmanager → AIOps engine: reports alerts (evidence: `api/app/aiops/engine.py`)
- AIOps engine → Incident diagnosis: collects evidence (evidence: `api/app/aiops/engine.py`)
- AIOps engine → Slack notifications: posts incident (evidence: `api/app/aiops/engine.py`)
- Slack notifications → Slack: notifies operators
- AIOps engine → Incident store: tracks incidents (evidence: `api/app/aiops/engine.py`)
