> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the GST Processor works under the hood

## Core Components

<AccordionGroup>
  <Accordion title="Frontend — Streamlit UI" icon="display">
    Provides an interactive, step-by-step user interface. Users select their company, define filters, and upload files.

    Supports two modes:

    * **Single Processing Mode** — processes one company's inputs for a specific location
    * **State Consolidation Mode** — merges multiple locations/companies for a state into a single sheet, with Document Summaries (e.g. cancelled invoice counts)
  </Accordion>

  <Accordion title="Dynamic SOP Manager (sop_manager.py)" icon="gear">
    Instead of hardcoded rules, each company (e.g. Britannia, Godrej, Sunpure) has its own SOP configuration file inside the `sops/` directory.

    The SOP controls:

    * Which files are required for upload
    * Standard column definitions
    * Custom logic rules

    The main application flow never changes — only the injected SOP does.
  </Accordion>

  <Accordion title="Data Processing Engine (Pandas)" icon="table">
    * Fast, memory-efficient Excel/CSV parsing via `pd.read_excel` and `pd.read_csv`
    * Column standardization — maps varying vendor column names to a standard set
    * VLOOKUP-style matching using dictionaries and `Series.map()` — avoids `JOIN` operations that could accidentally duplicate rows
  </Accordion>

  <Accordion title="Unit Standardizer (unit_standardizer.py)" icon="ruler">
    Automatically maps shorthand units in raw data (e.g. `PCS`, `KG`, `Ltr`) to standardized full-form outputs required by downstream GST systems.
  </Accordion>
</AccordionGroup>

***

## Design Rules

| Rule                       | Description                                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| **No Deduplication**       | Duplicate rows in the input Bill Details are strictly preserved in the output                      |
| **Row Cardinality Check**  | Output row count must exactly match the input Bill Details file                                    |
| **Lookup Strategy**        | No table merges — missing lookup values result in empty or `UNREGISTERED` fields, never extra rows |
| **Preservation of Totals** | Taxable amounts and taxes are taken directly from inputs — no overriding calculations              |