# nahian369/e_return_nbr architecture

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

- Interactive diagram: https://gitdiagram.com/nahian369/e_return_nbr
- Repository: https://github.com/nahian369/e_return_nbr

## Overview

This repository is a Bangladesh NBR e-Return assistant blueprint, not an autonomous filing service. A taxpayer prepares tax documents and annual figures; local tools extract and classify data or produce an experimental optimization report, then an AI agent uses the runbook and browser bridge to fill the government portal and save a draft. The taxpayer reviews, pays, and submits personally. The README documents the browser workflow; sampled source confirms extraction, classification, e-Return parsing, and optimization. Portal automation internals are external to this repository.

Main entry points: [`tools/extract.py`](https://github.com/nahian369/e_return_nbr/blob/main/tools/extract.py) (Document extractor), [`templates`](https://github.com/nahian369/e_return_nbr/tree/main/templates) (Annual tax inputs), [`tools/optimize.py`](https://github.com/nahian369/e_return_nbr/blob/main/tools/optimize.py) (Tax optimizer), [`opencode.json`](https://github.com/nahian369/e_return_nbr/blob/main/opencode.json) (Browser bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guides["Filing guidance"]
  node_tax_guide["Tax guide"]
  node_agent_runbook["Agent runbook"]
  node_optimization_guide["Optimization guidance<br/>[tax_optimize.md]"]
end

subgraph group_data_tools["Data preparation"]
  node_source_documents["Tax documents"]
  node_document_extractor["Document extractor<br/>[extract.py]"]
  node_file_classifier["File classifier<br/>[classify.py]"]
  node_ereturn_parser["e-Return parser<br/>[ereturn.py]"]
  node_staging_data["Staging JSON"]
  node_annual_inputs["Annual tax inputs"]
  node_tax_optimizer["Tax optimizer<br/>[optimize.py]"]
  node_optimization_report["Optimization report"]
end

subgraph group_agent_flow["Agent-assisted filing"]
  node_ai_agent(("AI agent"))
  node_browser_bridge["Browser bridge<br/>[opencode.json]"]
  node_government_portal["NBR e-Return"]
  node_saved_draft["Saved draft"]
end

node_taxpayer(("Taxpayer"))

node_taxpayer -->|"provides"| node_source_documents
node_source_documents -->|"extracts from"| node_document_extractor
node_document_extractor -->|"classifies with"| node_file_classifier
node_document_extractor -->|"parses returns with"| node_ereturn_parser
node_document_extractor -->|"writes"| node_staging_data
node_taxpayer -->|"prepares"| node_annual_inputs
node_annual_inputs -->|"provides inputs"| node_tax_optimizer
node_tax_optimizer -->|"renders"| node_optimization_report
node_taxpayer -->|"reads"| node_tax_guide
node_taxpayer -->|"reads"| node_optimization_guide
node_taxpayer -->|"follows"| node_agent_runbook
node_taxpayer -->|"instructs"| node_ai_agent
node_ai_agent -->|"controls browser via"| node_browser_bridge
node_browser_bridge -->|"operates in"| node_government_portal
node_ai_agent -->|"fills forms"| node_government_portal
node_government_portal -->|"saves draft"| node_saved_draft
node_taxpayer -->|"reviews"| node_saved_draft
node_taxpayer -->|"pays and submits"| node_government_portal

click node_tax_guide "https://github.com/nahian369/e_return_nbr/blob/main/Tax-Filing-Guide-Bangladesh.md"
click node_agent_runbook "https://github.com/nahian369/e_return_nbr/blob/main/NBR-eReturn-Agentic-Entry-Plan.md"
click node_optimization_guide "https://github.com/nahian369/e_return_nbr/blob/main/tax_optimize.md"
click node_document_extractor "https://github.com/nahian369/e_return_nbr/blob/main/tools/extract.py"
click node_file_classifier "https://github.com/nahian369/e_return_nbr/blob/main/tools/classify.py"
click node_ereturn_parser "https://github.com/nahian369/e_return_nbr/blob/main/tools/parsers/ereturn.py"
click node_annual_inputs "https://github.com/nahian369/e_return_nbr/tree/main/templates"
click node_tax_optimizer "https://github.com/nahian369/e_return_nbr/blob/main/tools/optimize.py"
click node_browser_bridge "https://github.com/nahian369/e_return_nbr/blob/main/opencode.json"

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_tax_guide,node_agent_runbook,node_optimization_guide toneBlue
class node_source_documents,node_document_extractor,node_file_classifier,node_ereturn_parser,node_staging_data,node_annual_inputs,node_tax_optimizer,node_optimization_report toneAmber
class node_ai_agent,node_browser_bridge,node_government_portal,node_saved_draft toneMint
class node_taxpayer toneIndigo
```

## Components

### Filing guidance

- [Tax guide](https://github.com/nahian369/e_return_nbr/blob/main/Tax-Filing-Guide-Bangladesh.md): `Tax-Filing-Guide-Bangladesh.md`
- [Agent runbook](https://github.com/nahian369/e_return_nbr/blob/main/NBR-eReturn-Agentic-Entry-Plan.md): `NBR-eReturn-Agentic-Entry-Plan.md`
- [Optimization guidance](https://github.com/nahian369/e_return_nbr/blob/main/tax_optimize.md): `tax_optimize.md`

### Data preparation

- **Tax documents**
- [Document extractor](https://github.com/nahian369/e_return_nbr/blob/main/tools/extract.py): `tools/extract.py`
- [File classifier](https://github.com/nahian369/e_return_nbr/blob/main/tools/classify.py): `tools/classify.py`
- [e-Return parser](https://github.com/nahian369/e_return_nbr/blob/main/tools/parsers/ereturn.py): `tools/parsers/ereturn.py`
- **Staging JSON**
- [Annual tax inputs](https://github.com/nahian369/e_return_nbr/tree/main/templates): `templates`
- [Tax optimizer](https://github.com/nahian369/e_return_nbr/blob/main/tools/optimize.py): `tools/optimize.py`
- **Optimization report**

### Agent-assisted filing

- **AI agent**
- [Browser bridge](https://github.com/nahian369/e_return_nbr/blob/main/opencode.json): `opencode.json`
- **NBR e-Return**
- **Saved draft**

### Other components

- **Taxpayer**

## Connections

- Taxpayer → Tax documents: provides (evidence: `README.md`)
- Tax documents → Document extractor: extracts from (evidence: `README.md`)
- Document extractor → File classifier: classifies with (evidence: `tools/extract.py`)
- Document extractor → e-Return parser: parses returns with (evidence: `tools/extract.py`)
- Document extractor → Staging JSON: writes (evidence: `README.md`)
- Taxpayer → Annual tax inputs: prepares (evidence: `README.md`)
- Annual tax inputs → Tax optimizer: provides inputs (evidence: `tools/optimize.py`)
- Tax optimizer → Optimization report: renders (evidence: `tools/optimize.py`)
- Taxpayer → Tax guide: reads (evidence: `README.md`)
- Taxpayer → Optimization guidance: reads (evidence: `README.md`)
- Taxpayer → Agent runbook: follows (evidence: `README.md`)
- Taxpayer → AI agent: instructs (evidence: `README.md`)
- AI agent → Browser bridge: controls browser via (evidence: `README.md`)
- Browser bridge → NBR e-Return: operates in (evidence: `README.md`)
- AI agent → NBR e-Return: fills forms (evidence: `README.md`)
- NBR e-Return → Saved draft: saves draft (evidence: `README.md`)
- Taxpayer → Saved draft: reviews (evidence: `README.md`)
- Taxpayer → NBR e-Return: pays and submits (evidence: `README.md`)
