# phatnd249/tool_invoice architecture

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

- Interactive diagram: https://gitdiagram.com/phatnd249/tool_invoice
- Repository: https://github.com/phatnd249/tool_invoice

## Overview

Invoice Download Tool is a web application for managing taxpayer companies and retrieving their electronic invoices from Vietnam’s GDT. Users authenticate, register or sign into companies, then download invoice archives and inspect or export invoice data; schedules automate retrieval. The frontend also manages users, roles and permissions, feedback, and Google Drive backups. The graph combines explicit frontend routes and sampled backend calls with capabilities documented in the README; several backend integrations are represented at subsystem level because their implementations were not sampled.

Main entry points: [`frontend/src/App.tsx`](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/App.tsx) (Web app routes), [`backend/src/prisma/prisma.service.ts`](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/prisma/prisma.service.ts) (Application database), [`backend/src/auth/auth.service.ts`](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/auth/auth.service.ts) (Authentication API), [`backend/src/invoices/invoices.controller.ts`](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoices.controller.ts) (Invoice endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_web["Web app routes<br/>[App.tsx]"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_invoiceui["Invoice screens<br/>[InvoicesPage.tsx]"]
  node_progressui["Download progress"]
  node_backupui["Backup screen<br/>[BackupPage.tsx]"]
  node_adminui["Admin screens<br/>[UsersPage.tsx]"]
end

subgraph group_access["Identity and access"]
  node_authapi["Authentication API<br/>[auth.service.ts]"]
  node_userapi["User management<br/>[users.service.ts]"]
  node_permissions["Permission checks"]
  node_db[("Application database<br/>[prisma.service.ts]")]
  node_mail["Email delivery<br/>[mail.service.ts]"]
end

subgraph group_invoices["Invoice operations"]
  node_invoiceapi["Invoice endpoints"]
  node_download["Invoice download"]
  node_gdtquery["GDT invoice query"]
  node_persistence["Invoice persistence"]
  node_preview["Invoice preview<br/>[preview.service.ts]"]
  node_reports["PDF and Excel export<br/>[excel.service.ts]"]
end

subgraph group_business["Business management"]
  node_companyapi["Company management"]
  node_companyservice["Company operations"]
  node_schedules["Download schedules"]
  node_runner["Schedule runner"]
  node_feedback["Feedback endpoint"]
end

subgraph group_backup["Backup and integrations"]
  node_backupapi["Backup endpoints"]
  node_backupservice["Backup orchestration<br/>[backup.service.ts]"]
  node_drive["Google Drive"]
end

node_user(("User"))
node_gdt{{"GDT services"}}
node_gemini{{"Gemini captcha help"}}

node_user -->|"uses"| node_web
node_web -->|"loads auth"| node_authui
node_web -->|"routes to"| node_invoiceui
node_web -->|"routes to"| node_backupui
node_web -->|"routes to"| node_adminui
node_user -.->|"authenticates"| node_authapi
node_authapi -->|"reads and writes"| node_db
node_authapi -->|"sends verification"| node_mail
node_adminui -.->|"manages users"| node_userapi
node_userapi -.->|"persists users"| node_db
node_companyapi -->|"dispatches"| node_companyservice
node_companyservice -.->|"authenticates company"| node_gdt
node_invoiceui -.->|"requests invoices"| node_invoiceapi
node_invoiceapi -.->|"dispatches downloads"| node_download
node_download -.->|"queries invoices"| node_gdtquery
node_gdtquery -->|"fetches invoice pages"| node_gdt
node_download -.->|"stores downloads"| node_persistence
node_invoiceapi -.->|"serves previews"| node_preview
node_preview -->|"reads invoice data"| node_db
node_preview -.->|"exports invoice data"| node_reports
node_user -.->|"configures schedules"| node_schedules
node_runner -.->|"executes schedules"| node_schedules
node_schedules -.->|"stores schedule data"| node_db
node_backupui -.->|"manages backups"| node_backupapi
node_backupapi -->|"dispatches"| node_backupservice
node_backupapi -->|"manages OAuth"| node_drive
node_backupservice -->|"backs up to"| node_drive
node_backupservice -->|"reads backup state"| node_db
node_companyservice -.->|"solves captcha"| node_gemini
node_user -.->|"submits feedback"| node_feedback

click node_web "https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_invoiceui "https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/invoices/InvoicesPage.tsx"
click node_progressui "https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/invoices/DownloadProgress.tsx"
click node_backupui "https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/backup/BackupPage.tsx"
click node_adminui "https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/users/UsersPage.tsx"
click node_authapi "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/auth/auth.service.ts"
click node_userapi "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/users/users.service.ts"
click node_permissions "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/auth/guards/permissions.guard.ts"
click node_db "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/prisma/prisma.service.ts"
click node_companyapi "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/companies/companies.controller.ts"
click node_companyservice "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/companies/companies.service.ts"
click node_schedules "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/schedules/schedules.controller.ts"
click node_runner "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/schedules/scheduler.runner.ts"
click node_invoiceapi "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoices.controller.ts"
click node_download "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoice-downloader.service.ts"
click node_gdtquery "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/gdt/gdt-query-client.service.ts"
click node_persistence "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoices-persistence.service.ts"
click node_preview "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/preview.service.ts"
click node_reports "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/excel.service.ts"
click node_backupapi "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/backup/backup.controller.ts"
click node_backupservice "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/backup/backup.service.ts"
click node_drive "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/backup/google-drive.service.ts"
click node_mail "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/mail/mail.service.ts"
click node_feedback "https://github.com/phatnd249/tool_invoice/blob/main/backend/src/feedback/feedback.controller.ts"

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_authui,node_invoiceui,node_progressui,node_backupui,node_adminui,node_user toneBlue
class node_authapi,node_userapi,node_permissions,node_db,node_mail toneAmber
class node_invoiceapi,node_download,node_gdtquery,node_persistence,node_preview,node_reports toneMint
class node_companyapi,node_companyservice,node_schedules,node_runner,node_feedback toneRose
class node_backupapi,node_backupservice,node_drive,node_gdt,node_gemini toneIndigo
```

## Components

### Web interface

- [Web app routes](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Invoice screens](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/invoices/InvoicesPage.tsx): `frontend/src/pages/invoices/InvoicesPage.tsx`
- [Download progress](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/invoices/DownloadProgress.tsx): `frontend/src/pages/invoices/DownloadProgress.tsx`
- [Backup screen](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/backup/BackupPage.tsx): `frontend/src/pages/backup/BackupPage.tsx`
- [Admin screens](https://github.com/phatnd249/tool_invoice/blob/main/frontend/src/pages/users/UsersPage.tsx): `frontend/src/pages/users/UsersPage.tsx`

### Identity and access

- [Authentication API](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [User management](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/users/users.service.ts): `backend/src/users/users.service.ts`
- [Permission checks](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/auth/guards/permissions.guard.ts): `backend/src/auth/guards/permissions.guard.ts`
- [Application database](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/prisma/prisma.service.ts): `backend/src/prisma/prisma.service.ts`
- [Email delivery](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/mail/mail.service.ts): `backend/src/mail/mail.service.ts`

### Invoice operations

- [Invoice endpoints](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoices.controller.ts): `backend/src/invoices/invoices.controller.ts`
- [Invoice download](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoice-downloader.service.ts): `backend/src/invoices/invoice-downloader.service.ts`
- [GDT invoice query](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/gdt/gdt-query-client.service.ts): `backend/src/invoices/gdt/gdt-query-client.service.ts`
- [Invoice persistence](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/invoices-persistence.service.ts): `backend/src/invoices/invoices-persistence.service.ts`
- [Invoice preview](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/preview.service.ts): `backend/src/invoices/preview.service.ts`
- [PDF and Excel export](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/invoices/excel.service.ts): `backend/src/invoices/excel.service.ts`

### Business management

- [Company management](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/companies/companies.controller.ts): `backend/src/companies/companies.controller.ts`
- [Company operations](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/companies/companies.service.ts): `backend/src/companies/companies.service.ts`
- [Download schedules](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/schedules/schedules.controller.ts): `backend/src/schedules/schedules.controller.ts`
- [Schedule runner](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/schedules/scheduler.runner.ts): `backend/src/schedules/scheduler.runner.ts`
- [Feedback endpoint](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/feedback/feedback.controller.ts): `backend/src/feedback/feedback.controller.ts`

### Backup and integrations

- [Backup endpoints](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/backup/backup.controller.ts): `backend/src/backup/backup.controller.ts`
- [Backup orchestration](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/backup/backup.service.ts): `backend/src/backup/backup.service.ts`
- [Google Drive](https://github.com/phatnd249/tool_invoice/blob/main/backend/src/backup/google-drive.service.ts): `backend/src/backup/google-drive.service.ts`

### Other components

- **User**
- **GDT services**
- **Gemini captcha help**

## Connections

- User → Web app routes: uses (evidence: `frontend/src/App.tsx`)
- Web app routes → Auth context: loads auth (evidence: `frontend/src/App.tsx`)
- Web app routes → Invoice screens: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Backup screen: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Admin screens: routes to (evidence: `frontend/src/App.tsx`)
- User → Authentication API: authenticates (evidence: `README.md`)
- Authentication API → Application database: reads and writes (evidence: `backend/src/auth/auth.service.ts`)
- Authentication API → Email delivery: sends verification (evidence: `backend/src/auth/auth.service.ts`)
- Admin screens → User management: manages users (evidence: `README.md`)
- User management → Application database: persists users
- Company management → Company operations: dispatches (evidence: `backend/src/companies/companies.controller.ts`)
- Company operations → GDT services: authenticates company (evidence: `README.md`)
- Invoice screens → Invoice endpoints: requests invoices (evidence: `README.md`)
- Invoice endpoints → Invoice download: dispatches downloads (evidence: `README.md`)
- Invoice download → GDT invoice query: queries invoices (evidence: `README.md`)
- GDT invoice query → GDT services: fetches invoice pages (evidence: `backend/src/invoices/gdt/gdt-query-client.service.ts`)
- Invoice download → Invoice persistence: stores downloads (evidence: `README.md`)
- Invoice endpoints → Invoice preview: serves previews (evidence: `README.md`)
- Invoice preview → Application database: reads invoice data (evidence: `backend/src/invoices/preview.service.ts`)
- Invoice preview → PDF and Excel export: exports invoice data (evidence: `README.md`)
- User → Download schedules: configures schedules (evidence: `README.md`)
- Schedule runner → Download schedules: executes schedules
- Download schedules → Application database: stores schedule data (evidence: `README.md`)
- Backup screen → Backup endpoints: manages backups (evidence: `README.md`)
- Backup endpoints → Backup orchestration: dispatches (evidence: `backend/src/backup/backup.controller.ts`)
- Backup endpoints → Google Drive: manages OAuth (evidence: `backend/src/backup/backup.controller.ts`)
- Backup orchestration → Google Drive: backs up to (evidence: `backend/src/backup/backup.service.ts`)
- Backup orchestration → Application database: reads backup state (evidence: `backend/src/backup/backup.service.ts`)
- Company operations → Gemini captcha help: solves captcha (evidence: `README.md`)
- User → Feedback endpoint: submits feedback (evidence: `README.md`)
