# resilient-tech/india-compliance architecture

> Architecture diagram of the GitHub repository resilient-tech/india-compliance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/resilient-tech/india-compliance
- Repository: https://github.com/resilient-tech/india-compliance

## Overview

##### Project type and purpose
- This is an “app” (plugin) built on top of the Frappe Framework and ERPNext.
- It extends ERPNext by adding custom DocTypes, client scripts, server-side controllers, reports, and a standalone Vue-based India Compliance Account front-end.
- Its purpose is to simplify Indian tax compliance: GSTR-1 preparation, GSTR-2A/2B reconciliation, e-invoice & e-waybill integration, real-time validation, reporting, and an account portal for API access.

##### File structure
- Top-level:
- Configuration & CI (.github, pyproject.toml, setup.py, hooks.py, patches, etc.)
- App package: `india_compliance/`
- Public assets & front-end SPA: `india_compliance/public/js/` (Vue components, bundles)
- Doctypes & overrides under `india_compliance/gst_india/` and `india_compliance/audit_trail/` etc.
- Utilities & API wrappers: `india_compliance/utils/` and `gst_india/utils/`
- Reports: many `india_compliance/gst_india/report/*` folders
- Web templates & print formats for invoices and QR codes
- Pattern: MVC
- Models: DocType JSON + Python classes
- Views: Frappe web templates + client scripts + Vue SPA
- Controllers: Python API classes, server scripts, scheduler jobs, patch scripts
- External integrations are signaled by `gst_india/api_classes` and `gst_india/utils/api.py`.

##### Key insights from README
- Reinforces that India Compliance is a Frappe/ERPNext app.
- Features rely on government GST APIs (external services).
- There is also a separate “India Compliance Account” SPA (Vue, under `public/js/india_compliance_account`).

a. Frappe Framework & ERPNext Core
- HTTP server (Gunicorn/WSGI)
- Scheduler & background jobs
- ORM layer → MariaDB/MySQL + Redis cache/queue
- Built-in web UI
b. India Compliance App (this project)
- DocTypes & Models (GST settings, logs, registers, reconciliation tool)
- Server-side controllers & API wrappers (under `gst_india/api_classes` & `utils/api.py`)
- Patch scripts & migrations (patches folder)
- Reports (Python + JS under `report/`)
- Web templates & print formats (QR code templates, HTML/CSS)
- Client scripts (Frappe page customizations in JS under doctype folders)
- Scheduler hooks (hooks.py triggers jobs for e-invoice/e-waybill retry, data sync)
c. India Compliance Account SPA
- Vue.js front-end (components, router, store)
- Services (AuthService, AccountService) interacting with a custom REST API endpoint in the app
d. External Services
- GST APIs: e-invoice IRP, e-waybill, GSTIN validation, tax return endpoints
- ERPNext (core) APIs for user auth, database operations
e. Database & Cache
- MariaDB/MySQL storing DocType records
- Redis for caching, job queue
f. Developer / CI pipelines
- GitHub Actions for tests, linting, release workflows

##### Relationships and interactions
- User (browser) →
- Frappe web UI (DocType forms, reports) & India Compliance Account SPA →
- Frappe HTTP server →
- India Compliance controllers →
- Frappe ORM → MariaDB/Redis
- Background scheduler/job →
- India Compliance tasks (e-waybill generation, data sync) →
- External Government GST APIs
- Admin / Developer → GitHub → CI workflows → deploy to server

##### Important architectural patterns
- MVC via Frappe: DocType JSON (model), Python scripts (controller), client scripts & web templates (view)
- Modularization by domain: `gst_india`, `audit_trail`, `income_tax_india`, `vat_india`
- External API adapters isolating government API calls under `api_classes` and `utils/api.py`
- Scheduler jobs for asynchronous compliance tasks
- Vue SPA decoupled from Frappe UI, communicating over REST

##### Detail level
- Drill into a representative module (e.g., e-invoice flow):
1. DocType “E-Invoice” form → Client script triggers action → Server API class → External IRP → Response → DocType log
2. Report generation: scheduled job reads DocType records → Python report class → JSON → JS renders table
- Patterns:
- “api_classes” implement Adapter pattern
- Patches apply at install/update time (migration layer)
- Client scripts use event hooks on DocType forms

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User (Browser)"]:::user
    User --> FrappeServer["Frappe HTTP Server"]:::core

    subgraph "Core Platform"
        FrappeServer
        Scheduler["Scheduler/Worker"]:::core
        MySQL[(MariaDB/MySQL)]:::db
        Redis[(Redis Cache/Queue)]:::db
    end

    FrappeServer --> IndiaApp["India Compliance App"]:::extension
    Scheduler --> IndiaApp

    subgraph "India Compliance App"
        subgraph "DocTypes & Models"
            DocTypes["GST DocTypes & Models"]:::extension
        end
        subgraph "Domain Modules"
            AuditDoct["audit_trail/doctype"]:::extension
            AuditOverride["audit_trail/overrides"]:::extension
            IncomeDoct["income_tax_india/doctype"]:::extension
            IncomeOverride["income_tax_india/overrides"]:::extension
            VATDoct["vat_india/doctype"]:::extension
        end
        subgraph "API & Utils"
            APIClasses["api_classes"]:::extension
            APIUtils["utils/api.py"]:::extension
            Utils["gst_india/utils"]:::extension
        end
        subgraph "Utility Modules"
            CustomFields["custom_fields.py"]:::extension
            DBUtils["db_utils.py"]:::extension
        end
        subgraph "Reports"
            ReportsNode["gst_india/report"]:::extension
        end
        subgraph "Web Templates & Print Formats"
            WebT["web_template"]:::extension
            PrintFmt["print_format"]:::extension
        end
        subgraph "Client Scripts"
            ClientGST["gst_india/client_scripts"]:::extension
            ClientAudit["audit_trail/client_scripts"]:::extension
        end
        Patches["patches"]:::extension
        Hooks["hooks.py"]:::extension
        CI["GitHub CI & Workflows"]:::extension
    end

    IndiaApp --> MySQL
    IndiaApp --> Redis
    IndiaApp --> GSTAPIs["Government GST APIs"]:::external
    Scheduler --> GSTAPIs

    User --> SPA["India Compliance Account SPA (Vue.js)"]:::spa
    SPA --> FrappeServer

    subgraph "External Services"
        GSTAPIs
    end

    click DocTypes "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/doctype/"
    click AuditDoct "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/audit_trail/doctype/"
    click AuditOverride "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/audit_trail/overrides/"
    click IncomeDoct "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/income_tax_india/doctype/"
    click IncomeOverride "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/income_tax_india/overrides/"
    click VATDoct "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/vat_india/doctype/"
    click APIClasses "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/api_classes/"
    click APIUtils "https://github.com/resilient-tech/india-compliance/blob/develop/india_compliance/gst_india/utils/api.py"
    click Utils "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/utils/"
    click CustomFields "https://github.com/resilient-tech/india-compliance/blob/develop/india_compliance/utils/custom_fields.py"
    click DBUtils "https://github.com/resilient-tech/india-compliance/blob/develop/india_compliance/db_utils.py"
    click ReportsNode "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/report/"
    click WebT "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/web_template/"
    click PrintFmt "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/print_format/"
    click ClientGST "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/gst_india/client_scripts/"
    click ClientAudit "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/audit_trail/client_scripts/"
    click Patches "https://github.com/resilient-tech/india-compliance/tree/develop/india_compliance/patches/"
    click Hooks "https://github.com/resilient-tech/india-compliance/blob/develop/india_compliance/hooks.py"
    click CI "https://github.com/resilient-tech/india-compliance/tree/develop/.github/workflows/"
    classDef core fill:#E0F7FA,stroke:#006064,color:#006064
    classDef extension fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef spa fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef external fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C
    classDef db fill:#EDE7F6,stroke:#4527A0,color:#4527A0
    classDef user fill:#FFFFFF,stroke:#000000,color:#000000
```
