# cchioru/tax_legal_final_version architecture

> Architecture diagram of the GitHub repository cchioru/tax_legal_final_version, 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/cchioru/tax_legal_final_version
- Repository: https://github.com/cchioru/tax_legal_final_version

## Overview

This repository implements a Thai personal-income-tax advisory chatbot on LINE, with workflow-automated, retrieval-grounded answers and deterministic tax calculations. The main path is a LINE message through n8n’s consent-aware answering flow to a reply or push response; separate branches cover legal-text lookup, feedback, user reports, and a privacy-restricted admin portal. Evaluation scripts support the research and quality-measurement capability. Workflow internals are represented from the README rather than inspected source; their edges cite that documentation.

Main entry points: [`n8n/workflows/tax-advisor-workflow.json`](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json) (Event and answer workflow), [`postgres`](https://github.com/cchioru/tax_legal_final_version/tree/main/postgres) (PostgreSQL tax data), [`admin/server.js`](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/server.js) (Admin web server), [`admin/knowledge.js`](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/knowledge.js) (Knowledge management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["LINE interaction"]
  node_line_api["LINE Messaging API"]
  node_tunnel["ngrok endpoint"]
  node_dispatch["Reply or push dispatch"]
end

subgraph group_answering["Answering workflow"]
  node_workflow["Event and answer workflow"]
  node_consent["Consent and routing"]
  node_agent["AI answer agent"]
  node_llm["Gemini language model"]
  node_calculator["Tax and penalty calculator<br/>[tax-calculator.js]"]
  node_postprocess["Answer checks and formatting"]
end

subgraph group_knowledge["Tax knowledge"]
  node_retrieval["Keyword retrieval"]
  node_law_lookup["Revenue Code lookup"]
  node_database[("PostgreSQL tax data")]
end

subgraph group_operations["Admin operations"]
  node_admin_server["Admin web server<br/>[server.js]"]
  node_admin_knowledge["Knowledge management<br/>[knowledge.js]"]
  node_admin_db["Read-only admin database access<br/>[db.js]"]
  node_admin_retrieval["Search preview<br/>[retrieval.js]"]
  node_admin_views["Admin charts and pages<br/>[chart.js]"]
end

subgraph group_research["Evaluation"]
  node_evaluation["Accuracy and coverage evaluation"]
end

node_taxpayer(("LINE user"))

node_taxpayer -->|"sends messages"| node_line_api
node_line_api -->|"webhook events"| node_tunnel
node_tunnel -->|"forwards events"| node_workflow
node_workflow -->|"routes events"| node_consent
node_workflow -->|"retrieves knowledge"| node_retrieval
node_workflow -->|"stores user data"| node_database
node_consent -->|"routes by consent"| node_agent
node_consent -->|"records consent"| node_database
node_agent -->|"generates answers"| node_llm
node_agent -->|"calls tools"| node_calculator
node_agent -->|"calls tools"| node_law_lookup
node_agent -->|"stores consented chats"| node_database
node_retrieval -->|"searches knowledge"| node_database
node_law_lookup -->|"reads current code"| node_database
node_workflow -->|"checks and formats"| node_postprocess
node_workflow -->|"selects reply channel"| node_dispatch
node_dispatch -->|"sends answer"| node_line_api
node_admin_server -->|"queries data"| node_admin_db
node_admin_server -->|"routes knowledge pages"| node_admin_knowledge
node_admin_server -->|"renders dashboard"| node_admin_views
node_admin_knowledge -->|"reads and writes entries"| node_admin_db
node_admin_knowledge -->|"previews searches"| node_admin_retrieval
node_admin_db -->|"queries PostgreSQL"| node_database
node_evaluation -->|"measures calculations"| node_calculator
node_evaluation -->|"checks coverage"| node_retrieval

click node_workflow "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_consent "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_retrieval "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_agent "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_calculator "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/tools/tax-calculator.js"
click node_law_lookup "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_postprocess "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_dispatch "https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json"
click node_database "https://github.com/cchioru/tax_legal_final_version/tree/main/postgres"
click node_admin_server "https://github.com/cchioru/tax_legal_final_version/blob/main/admin/server.js"
click node_admin_knowledge "https://github.com/cchioru/tax_legal_final_version/blob/main/admin/knowledge.js"
click node_admin_db "https://github.com/cchioru/tax_legal_final_version/blob/main/admin/db.js"
click node_admin_retrieval "https://github.com/cchioru/tax_legal_final_version/blob/main/admin/retrieval.js"
click node_admin_views "https://github.com/cchioru/tax_legal_final_version/blob/main/admin/chart.js"
click node_evaluation "https://github.com/cchioru/tax_legal_final_version/tree/main/evaluation"

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_line_api,node_tunnel,node_dispatch,node_taxpayer toneBlue
class node_workflow,node_consent,node_agent,node_llm,node_calculator,node_postprocess toneAmber
class node_retrieval,node_law_lookup,node_database toneMint
class node_admin_server,node_admin_knowledge,node_admin_db,node_admin_retrieval,node_admin_views toneRose
class node_evaluation toneIndigo
```

## Components

### LINE interaction

- **LINE Messaging API**
- **ngrok endpoint**
- [Reply or push dispatch](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`

### Answering workflow

- [Event and answer workflow](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`
- [Consent and routing](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`
- [AI answer agent](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`
- **Gemini language model**
- [Tax and penalty calculator](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/tools/tax-calculator.js): `n8n/tools/tax-calculator.js`
- [Answer checks and formatting](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`

### Tax knowledge

- [Keyword retrieval](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`
- [Revenue Code lookup](https://github.com/cchioru/tax_legal_final_version/blob/main/n8n/workflows/tax-advisor-workflow.json): `n8n/workflows/tax-advisor-workflow.json`
- [PostgreSQL tax data](https://github.com/cchioru/tax_legal_final_version/tree/main/postgres): `postgres`

### Admin operations

- [Admin web server](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/server.js): `admin/server.js`
- [Knowledge management](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/knowledge.js): `admin/knowledge.js`
- [Read-only admin database access](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/db.js): `admin/db.js`
- [Search preview](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/retrieval.js): `admin/retrieval.js`
- [Admin charts and pages](https://github.com/cchioru/tax_legal_final_version/blob/main/admin/chart.js): `admin/chart.js`

### Evaluation

- [Accuracy and coverage evaluation](https://github.com/cchioru/tax_legal_final_version/tree/main/evaluation): `evaluation`

### Other components

- **LINE user**

## Connections

- LINE user → LINE Messaging API: sends messages (evidence: `README.md`)
- LINE Messaging API → ngrok endpoint: webhook events (evidence: `README.md`)
- ngrok endpoint → Event and answer workflow: forwards events (evidence: `README.md`)
- Event and answer workflow → Consent and routing: routes events (evidence: `README.md`)
- Event and answer workflow → Keyword retrieval: retrieves knowledge (evidence: `README.md`)
- Event and answer workflow → PostgreSQL tax data: stores user data (evidence: `README.md`)
- Consent and routing → AI answer agent: routes by consent (evidence: `README.md`)
- Consent and routing → PostgreSQL tax data: records consent (evidence: `README.md`)
- AI answer agent → Gemini language model: generates answers (evidence: `README.md`)
- AI answer agent → Tax and penalty calculator: calls tools (evidence: `README.md`)
- AI answer agent → Revenue Code lookup: calls tools (evidence: `README.md`)
- AI answer agent → PostgreSQL tax data: stores consented chats (evidence: `README.md`)
- Keyword retrieval → PostgreSQL tax data: searches knowledge (evidence: `README.md`)
- Revenue Code lookup → PostgreSQL tax data: reads current code (evidence: `README.md`)
- Event and answer workflow → Answer checks and formatting: checks and formats (evidence: `README.md`)
- Event and answer workflow → Reply or push dispatch: selects reply channel (evidence: `README.md`)
- Reply or push dispatch → LINE Messaging API: sends answer (evidence: `README.md`)
- Admin web server → Read-only admin database access: queries data (evidence: `admin/server.js`)
- Admin web server → Knowledge management: routes knowledge pages (evidence: `admin/server.js`)
- Admin web server → Admin charts and pages: renders dashboard (evidence: `admin/server.js`)
- Knowledge management → Read-only admin database access: reads and writes entries (evidence: `admin/knowledge.js`)
- Knowledge management → Search preview: previews searches (evidence: `admin/knowledge.js`)
- Read-only admin database access → PostgreSQL tax data: queries PostgreSQL (evidence: `admin/db.js`)
- Accuracy and coverage evaluation → Tax and penalty calculator: measures calculations (evidence: `evaluation/run-accuracy-test.js`)
- Accuracy and coverage evaluation → Keyword retrieval: checks coverage (evidence: `evaluation/check-knowledge-coverage.js`)
