# tanbir-ahm/recourse architecture

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

- Interactive diagram: https://gitdiagram.com/tanbir-ahm/recourse
- Repository: https://github.com/tanbir-ahm/recourse

## Overview

Recourse is a plain-language legal-help product for people and families dealing with arrest, custody, cheque-bounce cases, or frozen accounts. A user enters a situation through the web app or WhatsApp; the situation is routed, relevant law and judgments are retrieved, and an answer is phrased with legal claims grounded in those sources. Separately, questionnaire answers or uploaded papers feed fixed-rule safeguard checks, which can support an editable petition draft. The README documents these boundaries and capabilities; sampled source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`app.py`](https://github.com/tanbir-ahm/recourse/blob/main/app.py) (Web app), [`whatsapp_bot.py`](https://github.com/tanbir-ahm/recourse/blob/main/whatsapp_bot.py) (WhatsApp front door), [`retrieval.py`](https://github.com/tanbir-ahm/recourse/blob/main/retrieval.py) (Legal retrieval), [`main.py`](https://github.com/tanbir-ahm/recourse/blob/main/main.py) (Safeguard checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["User channels"]
  node_web["Web app<br/>[app.py]"]
  node_whatsapp["WhatsApp front door<br/>[whatsapp_bot.py]"]
  node_conversation[("Chat context<br/>[whatsapp_store.py]")]
end

subgraph group_answer["Grounded answers"]
  node_router["Situation router<br/>[scenario_router.py]"]
  node_retrieval["Legal retrieval<br/>[retrieval.py]"]
  node_phrase["Grounded phrasing<br/>[chat_assistant.py]"]
  node_screen["Claim screen<br/>[second_reader.py]"]
end

subgraph group_assessment["Safeguard assessment"]
  node_upload["Uploaded papers<br/>[recourse_upload.py]"]
  node_rules["Safeguard checks<br/>[main.py]"]
  node_questions["Questionnaire flow<br/>[interview_flow.py]"]
  node_findings["Findings and severity<br/>[main.py]"]
end

subgraph group_legaldata["Legal knowledge"]
  node_documents[("Statutes and judgments<br/>[vaquill_search.py]")]
  node_doctrine["Doctrine anchors"]
  node_sections["Statute data"]
end

subgraph group_drafting["Drafting"]
  node_petition["Petition draft<br/>[petition_draft.py]"]
end

node_person(("Person or family"))
node_model{{"Language model"}}
node_result["Answer and next steps"]
node_pdf["Petition PDF"]

node_person -->|"asks or uploads"| node_web
node_person -->|"messages"| node_whatsapp
node_whatsapp -->|"reads and writes"| node_conversation
node_web -->|"routes situation"| node_router
node_whatsapp -->|"routes situation"| node_router
node_router -->|"selects legal context"| node_retrieval
node_retrieval -->|"retrieves passages"| node_documents
node_retrieval -->|"uses anchors"| node_doctrine
node_retrieval -->|"uses statute data"| node_sections
node_web -->|"requests explanation"| node_phrase
node_whatsapp -->|"requests explanation"| node_phrase
node_phrase -->|"phrases response"| node_model
node_retrieval -->|"provides sources"| node_phrase
node_phrase -->|"screens claims"| node_screen
node_screen -->|"returns checked answer"| node_result
node_web -->|"accepts documents"| node_upload
node_upload -->|"provides document facts"| node_rules
node_web -->|"collects answers"| node_questions
node_questions -->|"provides answers"| node_rules
node_rules -->|"checks legal provisions"| node_sections
node_rules -->|"grounds findings"| node_documents
node_rules -->|"produces verdict"| node_findings
node_findings -->|"supplies findings"| node_petition
node_web -->|"requests draft"| node_petition
node_petition -->|"renders document"| node_pdf
node_web -->|"shows answer"| node_result
node_whatsapp -->|"delivers reply"| node_result

click node_web "https://github.com/tanbir-ahm/recourse/blob/main/app.py"
click node_whatsapp "https://github.com/tanbir-ahm/recourse/blob/main/whatsapp_bot.py"
click node_conversation "https://github.com/tanbir-ahm/recourse/blob/main/whatsapp_store.py"
click node_router "https://github.com/tanbir-ahm/recourse/blob/main/scenario_router.py"
click node_retrieval "https://github.com/tanbir-ahm/recourse/blob/main/retrieval.py"
click node_phrase "https://github.com/tanbir-ahm/recourse/blob/main/chat_assistant.py"
click node_screen "https://github.com/tanbir-ahm/recourse/blob/main/second_reader.py"
click node_documents "https://github.com/tanbir-ahm/recourse/blob/main/vaquill_search.py"
click node_doctrine "https://github.com/tanbir-ahm/recourse/blob/main/statute_doctrine_map.py"
click node_sections "https://github.com/tanbir-ahm/recourse/blob/main/bns_section_data_v2.py"
click node_upload "https://github.com/tanbir-ahm/recourse/blob/main/recourse_upload.py"
click node_rules "https://github.com/tanbir-ahm/recourse/blob/main/main.py"
click node_questions "https://github.com/tanbir-ahm/recourse/blob/main/interview_flow.py"
click node_findings "https://github.com/tanbir-ahm/recourse/blob/main/main.py"
click node_petition "https://github.com/tanbir-ahm/recourse/blob/main/petition_draft.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_web,node_whatsapp,node_conversation toneBlue
class node_router,node_retrieval,node_phrase,node_screen toneAmber
class node_upload,node_rules,node_questions,node_findings toneMint
class node_documents,node_doctrine,node_sections toneRose
class node_petition,node_person,node_model,node_result,node_pdf toneIndigo
```

## Components

### User channels

- [Web app](https://github.com/tanbir-ahm/recourse/blob/main/app.py): `app.py`
- [WhatsApp front door](https://github.com/tanbir-ahm/recourse/blob/main/whatsapp_bot.py): `whatsapp_bot.py`
- [Chat context](https://github.com/tanbir-ahm/recourse/blob/main/whatsapp_store.py): `whatsapp_store.py`

### Grounded answers

- [Situation router](https://github.com/tanbir-ahm/recourse/blob/main/scenario_router.py): `scenario_router.py`
- [Legal retrieval](https://github.com/tanbir-ahm/recourse/blob/main/retrieval.py): `retrieval.py`
- [Grounded phrasing](https://github.com/tanbir-ahm/recourse/blob/main/chat_assistant.py): `chat_assistant.py`
- [Claim screen](https://github.com/tanbir-ahm/recourse/blob/main/second_reader.py): `second_reader.py`

### Safeguard assessment

- [Uploaded papers](https://github.com/tanbir-ahm/recourse/blob/main/recourse_upload.py): `recourse_upload.py`
- [Safeguard checks](https://github.com/tanbir-ahm/recourse/blob/main/main.py): `main.py`
- [Questionnaire flow](https://github.com/tanbir-ahm/recourse/blob/main/interview_flow.py): `interview_flow.py`
- [Findings and severity](https://github.com/tanbir-ahm/recourse/blob/main/main.py): `main.py`

### Legal knowledge

- [Statutes and judgments](https://github.com/tanbir-ahm/recourse/blob/main/vaquill_search.py): `vaquill_search.py`
- [Doctrine anchors](https://github.com/tanbir-ahm/recourse/blob/main/statute_doctrine_map.py): `statute_doctrine_map.py`
- [Statute data](https://github.com/tanbir-ahm/recourse/blob/main/bns_section_data_v2.py): `bns_section_data_v2.py`

### Drafting

- [Petition draft](https://github.com/tanbir-ahm/recourse/blob/main/petition_draft.py): `petition_draft.py`

### Other components

- **Person or family**
- **Language model**
- **Answer and next steps**
- **Petition PDF**

## Connections

- Person or family → Web app: asks or uploads
- Person or family → WhatsApp front door: messages
- WhatsApp front door → Chat context: reads and writes
- Web app → Situation router: routes situation
- WhatsApp front door → Situation router: routes situation
- Situation router → Legal retrieval: selects legal context
- Legal retrieval → Statutes and judgments: retrieves passages
- Legal retrieval → Doctrine anchors: uses anchors
- Legal retrieval → Statute data: uses statute data
- Web app → Grounded phrasing: requests explanation
- WhatsApp front door → Grounded phrasing: requests explanation
- Grounded phrasing → Language model: phrases response
- Legal retrieval → Grounded phrasing: provides sources
- Grounded phrasing → Claim screen: screens claims
- Claim screen → Answer and next steps: returns checked answer
- Web app → Uploaded papers: accepts documents
- Uploaded papers → Safeguard checks: provides document facts
- Web app → Questionnaire flow: collects answers
- Questionnaire flow → Safeguard checks: provides answers
- Safeguard checks → Statute data: checks legal provisions
- Safeguard checks → Statutes and judgments: grounds findings
- Safeguard checks → Findings and severity: produces verdict
- Findings and severity → Petition draft: supplies findings
- Web app → Petition draft: requests draft
- Petition draft → Petition PDF: renders document
- Web app → Answer and next steps: shows answer
- WhatsApp front door → Answer and next steps: delivers reply