# gargi-09/f1-tax-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/gargi-09/f1-tax-assistant
- Repository: https://github.com/gargi-09/f1-tax-assistant

## Overview

F-1 Tax Assistant is a Flask-backed conversational prototype for helping international students understand common U.S. tax filing questions. A student submits a question through the chat UI; the backend chooses an AI response when configured or a keyword-matched demo response otherwise, then returns guidance for display with confidence and source details. Separate UI tools support treaty lookup, form selection, glossary, and verification. The README documents these capabilities, but excerpts do not show all route implementations, so some UI-to-backend links rely on documented endpoints or are omitted.

Main entry points: [`static/js/script.js`](https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js) (Chat and tools), [`app.py`](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py) (Flask app), [`templates/index.html`](https://github.com/gargi-09/f1-tax-assistant/blob/main/templates/index.html) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Student interface"]
  node_chat["Chat interface<br/>[index.html]"]
  node_browser["Chat and tools<br/>[script.js]"]
  node_treaty_tool["Treaty lookup<br/>[script.js]"]
  node_form_tool["Form wizard<br/>[script.js]"]
  node_trust_ui["Trust and advisor UI<br/>[script.js]"]
end

subgraph group_guidance["Tax guidance"]
  node_flask["Flask app<br/>[app.py]"]
  node_scenario["Scenario responses<br/>[app.py]"]
  node_tax_reference["Tax reference data<br/>[app.py]"]
  node_confidence["Confidence details<br/>[app.py]"]
end

subgraph group_services["Response services"]
  node_demo_mode["Keyword matching<br/>[app.py]"]
  node_ai_mode["AI response<br/>[app.py]"]
end

node_student(("F-1 student"))
node_gemini{{"Gemini API"}}
node_openai{{"OpenAI API"}}

node_student -->|"asks question"| node_chat
node_chat -->|"submits input"| node_browser
node_browser -->|"posts message"| node_flask
node_flask -->|"returns response"| node_browser
node_browser -->|"renders answer"| node_chat
node_flask -->|"selects when no AI"| node_demo_mode
node_flask -->|"selects when enabled"| node_ai_mode
node_demo_mode -->|"matches keywords"| node_scenario
node_ai_mode -->|"requests generation"| node_gemini
node_ai_mode -.->|"may use provider"| node_openai
node_browser -->|"opens lookup"| node_treaty_tool
node_treaty_tool -->|"fetches treaty data"| node_flask
node_browser -->|"opens wizard"| node_form_tool
node_browser -->|"shows verification"| node_trust_ui
node_trust_ui -->|"loads confidence"| node_confidence
node_browser -.->|"shows tax details"| node_tax_reference

click node_chat "https://github.com/gargi-09/f1-tax-assistant/blob/main/templates/index.html"
click node_browser "https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js"
click node_flask "https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py"
click node_scenario "https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py"
click node_tax_reference "https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py"
click node_confidence "https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py"
click node_treaty_tool "https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js"
click node_form_tool "https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js"
click node_trust_ui "https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js"
click node_demo_mode "https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py"
click node_ai_mode "https://github.com/gargi-09/f1-tax-assistant/blob/main/app.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_chat,node_browser,node_treaty_tool,node_form_tool,node_trust_ui toneBlue
class node_flask,node_scenario,node_tax_reference,node_confidence toneAmber
class node_demo_mode,node_ai_mode,node_gemini,node_openai toneMint
class node_student toneIndigo
```

## Components

### Student interface

- [Chat interface](https://github.com/gargi-09/f1-tax-assistant/blob/main/templates/index.html): `templates/index.html`
- [Chat and tools](https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js): `static/js/script.js`
- [Treaty lookup](https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js): `static/js/script.js`
- [Form wizard](https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js): `static/js/script.js`
- [Trust and advisor UI](https://github.com/gargi-09/f1-tax-assistant/blob/main/static/js/script.js): `static/js/script.js`

### Tax guidance

- [Flask app](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py): `app.py`
- [Scenario responses](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py): `app.py`
- [Tax reference data](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py): `app.py`
- [Confidence details](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py): `app.py`

### Response services

- [Keyword matching](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py): `app.py`
- [AI response](https://github.com/gargi-09/f1-tax-assistant/blob/main/app.py): `app.py`

### Other components

- **F-1 student**
- **Gemini API**
- **OpenAI API**

## Connections

- F-1 student → Chat interface: asks question (evidence: `README.md`)
- Chat interface → Chat and tools: submits input (evidence: `static/js/script.js`)
- Chat and tools → Flask app: posts message (evidence: `static/js/script.js`)
- Flask app → Chat and tools: returns response (evidence: `app.py`)
- Chat and tools → Chat interface: renders answer (evidence: `static/js/script.js`)
- Flask app → Keyword matching: selects when no AI (evidence: `app.py`)
- Flask app → AI response: selects when enabled (evidence: `app.py`)
- Keyword matching → Scenario responses: matches keywords (evidence: `app.py`)
- AI response → Gemini API: requests generation (evidence: `app.py`)
- AI response → OpenAI API: may use provider (evidence: `README.md`)
- Chat and tools → Treaty lookup: opens lookup (evidence: `static/js/script.js`)
- Treaty lookup → Flask app: fetches treaty data (evidence: `static/js/script.js`)
- Chat and tools → Form wizard: opens wizard (evidence: `static/js/script.js`)
- Chat and tools → Trust and advisor UI: shows verification (evidence: `static/js/script.js`)
- Trust and advisor UI → Confidence details: loads confidence (evidence: `static/js/script.js`)
- Chat and tools → Tax reference data: shows tax details
