# sumaniya-sheikh/gst-invoice-system architecture

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

- Interactive diagram: https://gitdiagram.com/sumaniya-sheikh/gst-invoice-system
- Repository: https://github.com/sumaniya-sheikh/gst-invoice-system

## Overview

This is a web-based GST invoice compliance and finance-operations system for business users and administrators. Users authenticate, submit invoice data, review parsed invoices and compliance findings, correct records, and inspect risk and reporting views. The README documents GSTIN and tax validation, duplicate/anomaly detection, risk scoring, reports, and role-based access; the source excerpts confirm CSV parsing and invoice analysis. Several finance modules are listed but unsampled, so their internal calls are not asserted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/App.jsx) (Application shell), [`frontend/src/pages/MonthlyGstSummary.jsx`](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/MonthlyGstSummary.jsx) (Finance views), [`src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java`](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java) (Invoice ingestion and analysis), [`frontend/src/services/invoiceService.js`](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/services/invoiceService.js) (Invoice API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Application shell<br/>[App.jsx]"]
  node_auth_ui["Login and account<br/>[Login.jsx]"]
  node_invoice_ui["Invoice review<br/>[RecentInvoices.jsx]"]
  node_dashboard["Dashboard and issues<br/>[Dashboard.jsx]"]
  node_ops_ui["Finance views"]
  node_invoice_client["Invoice API client<br/>[invoiceService.js]"]
end

subgraph group_access["Identity and access"]
  node_auth_service["Authentication API client<br/>[authService.js]"]
  node_auth_controller["Authentication endpoints"]
  node_user_admin["User administration"]
end

subgraph group_compliance["Invoice compliance"]
  node_invoice_service["Invoice ingestion and analysis"]
  node_gstin_validator["GSTIN validation"]
  node_invoice_api["Invoice endpoints"]
end

subgraph group_operations["Finance operations"]
  node_vendor_ops["Vendor management and risk"]
  node_payment_ops["Payment tracking"]
  node_gst_reports["GST summaries and registers"]
  node_audit["Audit history"]
end

subgraph group_persistence["Domain data"]
  node_user_records[("User records")]
  node_invoice_records[("Invoice records")]
  node_issue_records[("Compliance issues")]
  node_correction_records[("Correction history")]
  node_finance_data[("Finance data stores")]
end

node_user(("Business user / admin"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_auth_ui
node_app -->|"renders"| node_invoice_ui
node_app -->|"renders"| node_dashboard
node_app -->|"routes to"| node_ops_ui
node_app -->|"checks session"| node_auth_service
node_app -->|"loads invoices"| node_invoice_client
node_auth_ui -.->|"authenticates"| node_auth_service
node_auth_service -.->|"HTTP requests"| node_auth_controller
node_auth_controller -->|"reads users"| node_user_records
node_user_admin -->|"manages users"| node_user_records
node_invoice_ui -.->|"requests invoices"| node_invoice_client
node_dashboard -.->|"uploads data"| node_invoice_client
node_invoice_client -.->|"HTTP requests"| node_invoice_api
node_invoice_api -.->|"delegates to"| node_invoice_service
node_invoice_service -->|"validates GSTIN"| node_gstin_validator
node_invoice_service -->|"saves and checks"| node_invoice_records
node_invoice_service -->|"stores findings"| node_issue_records
node_invoice_service -->|"stores corrections"| node_correction_records
node_ops_ui -.->|"views vendor data"| node_vendor_ops
node_ops_ui -.->|"views payments"| node_payment_ops
node_ops_ui -.->|"views summaries"| node_gst_reports
node_ops_ui -.->|"views audit data"| node_audit
node_vendor_ops -.->|"uses records"| node_finance_data
node_payment_ops -.->|"uses records"| node_finance_data
node_gst_reports -.->|"uses records"| node_finance_data
node_audit -.->|"uses records"| node_finance_data

click node_app "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/App.jsx"
click node_auth_ui "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/Login.jsx"
click node_invoice_ui "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/RecentInvoices.jsx"
click node_dashboard "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/Dashboard.jsx"
click node_ops_ui "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/MonthlyGstSummary.jsx"
click node_auth_service "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/services/authService.js"
click node_auth_controller "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/AuthController.java"
click node_user_admin "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/UserManagementController.java"
click node_user_records "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/UserRepository.java"
click node_invoice_service "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java"
click node_gstin_validator "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/validation/GstinValidator.java"
click node_invoice_api "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/InvoiceController.java"
click node_invoice_client "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/services/invoiceService.js"
click node_invoice_records "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceRepository.java"
click node_issue_records "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceIssueRepository.java"
click node_correction_records "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceCorrectionRepository.java"
click node_vendor_ops "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/VendorController.java"
click node_payment_ops "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/PaymentController.java"
click node_gst_reports "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/MonthlyGstSummaryController.java"
click node_audit "https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/AuditController.java"
click node_finance_data "https://github.com/sumaniya-sheikh/gst-invoice-system/tree/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository"

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_app,node_auth_ui,node_invoice_ui,node_dashboard,node_ops_ui,node_invoice_client,node_user toneBlue
class node_auth_service,node_auth_controller,node_user_admin toneAmber
class node_invoice_service,node_gstin_validator,node_invoice_api toneMint
class node_vendor_ops,node_payment_ops,node_gst_reports,node_audit toneRose
class node_user_records,node_invoice_records,node_issue_records,node_correction_records,node_finance_data toneIndigo
```

## Components

### Web application

- [Application shell](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login and account](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Invoice review](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/RecentInvoices.jsx): `frontend/src/pages/RecentInvoices.jsx`
- [Dashboard and issues](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Finance views](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/pages/MonthlyGstSummary.jsx): `frontend/src/pages/MonthlyGstSummary.jsx`
- [Invoice API client](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/services/invoiceService.js): `frontend/src/services/invoiceService.js`

### Identity and access

- [Authentication API client](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/frontend/src/services/authService.js): `frontend/src/services/authService.js`
- [Authentication endpoints](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/AuthController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/AuthController.java`
- [User administration](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/UserManagementController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/UserManagementController.java`

### Invoice compliance

- [Invoice ingestion and analysis](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java): `src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java`
- [GSTIN validation](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/validation/GstinValidator.java): `src/main/java/com/gstcompliance/gstinvoicesystem/validation/GstinValidator.java`
- [Invoice endpoints](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/InvoiceController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/InvoiceController.java`

### Finance operations

- [Vendor management and risk](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/VendorController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/VendorController.java`
- [Payment tracking](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/PaymentController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/PaymentController.java`
- [GST summaries and registers](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/MonthlyGstSummaryController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/MonthlyGstSummaryController.java`
- [Audit history](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/controller/AuditController.java): `src/main/java/com/gstcompliance/gstinvoicesystem/controller/AuditController.java`

### Domain data

- [User records](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/UserRepository.java): `src/main/java/com/gstcompliance/gstinvoicesystem/repository/UserRepository.java`
- [Invoice records](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceRepository.java): `src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceRepository.java`
- [Compliance issues](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceIssueRepository.java): `src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceIssueRepository.java`
- [Correction history](https://github.com/sumaniya-sheikh/gst-invoice-system/blob/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceCorrectionRepository.java): `src/main/java/com/gstcompliance/gstinvoicesystem/repository/InvoiceCorrectionRepository.java`
- [Finance data stores](https://github.com/sumaniya-sheikh/gst-invoice-system/tree/master/src/main/java/com/gstcompliance/gstinvoicesystem/repository): `src/main/java/com/gstcompliance/gstinvoicesystem/repository`

### Other components

- **Business user / admin**

## Connections

- Business user / admin → Application shell: uses (evidence: `frontend/src/App.jsx`)
- Application shell → Login and account: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Invoice review: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Dashboard and issues: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Finance views: routes to (evidence: `frontend/src/App.jsx`)
- Application shell → Authentication API client: checks session (evidence: `frontend/src/App.jsx`)
- Application shell → Invoice API client: loads invoices (evidence: `frontend/src/App.jsx`)
- Login and account → Authentication API client: authenticates
- Authentication API client → Authentication endpoints: HTTP requests
- Authentication endpoints → User records: reads users
- User administration → User records: manages users (evidence: `src/main/java/com/gstcompliance/gstinvoicesystem/controller/UserManagementController.java`)
- Invoice review → Invoice API client: requests invoices
- Dashboard and issues → Invoice API client: uploads data
- Invoice API client → Invoice endpoints: HTTP requests
- Invoice endpoints → Invoice ingestion and analysis: delegates to
- Invoice ingestion and analysis → GSTIN validation: validates GSTIN (evidence: `src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java`)
- Invoice ingestion and analysis → Invoice records: saves and checks (evidence: `src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java`)
- Invoice ingestion and analysis → Compliance issues: stores findings (evidence: `src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java`)
- Invoice ingestion and analysis → Correction history: stores corrections (evidence: `src/main/java/com/gstcompliance/gstinvoicesystem/service/InvoiceService.java`)
- Finance views → Vendor management and risk: views vendor data
- Finance views → Payment tracking: views payments
- Finance views → GST summaries and registers: views summaries
- Finance views → Audit history: views audit data
- Vendor management and risk → Finance data stores: uses records
- Payment tracking → Finance data stores: uses records
- GST summaries and registers → Finance data stores: uses records
- Audit history → Finance data stores: uses records
