# deepika-1020/leaklens architecture

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

## Overview

LeakLens is a Streamlit decision-support application for investigating e-commerce revenue leakage. A user submits a business question; the router classifies its intent and filters, the engine dispatches deterministic analysis over unified order data, and the reasoner turns calculated facts into a grounded briefing. The UI presents findings and evidence, then requires reviewer approval or rejection before recording an audit entry. The README also documents refund, delivery, discount, product, customer, and trend investigations. Some analytics modules are present but their runtime dispatch is not shown in the excerpts.

Main entry points: [`src/leaklens_engine.py`](https://github.com/deepika-1020/leaklens/blob/main/src/leaklens_engine.py) (Investigation engine), [`src/data_loader.py`](https://github.com/deepika-1020/leaklens/blob/main/src/data_loader.py) (Data preparation), [`app.py`](https://github.com/deepika-1020/leaklens/blob/main/app.py) (Decision UI), [`src/revenue_investigator.py`](https://github.com/deepika-1020/leaklens/blob/main/src/revenue_investigator.py) (Revenue investigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_ui["Decision UI<br/>[app.py]"]
end

subgraph group_orchestration["Query orchestration"]
  node_engine["Investigation engine<br/>[leaklens_engine.py]"]
  node_router["Intent router<br/>[query_router.py]"]
end

subgraph group_analytics["Deterministic analytics"]
  node_loader["Data preparation<br/>[data_loader.py]"]
  node_dataset[("Business CSVs")]
  node_trend["Revenue trends<br/>[trend_analyzer.py]"]
  node_revenue["Revenue investigation"]
  node_products["Product leakage"]
  node_customers["Customer analysis"]
  node_evidence["Evidence extraction<br/>[evidence_engine.py]"]
  node_investigator["Investigation analysis<br/>[investigator.py]"]
  node_leakage["Leakage detection"]
  node_decisions["Base decisions<br/>[decision_engine.py]"]
end

subgraph group_governance["Reasoning and governance"]
  node_reasoner["Grounded reasoner<br/>[reasoner.py]"]
  node_audit["Audit logger<br/>[audit_logger.py]"]
  node_trail[("Persistent audit trail<br/>[audit_trail.json]")]
end

node_user(("Business user"))
node_gemini{{"Gemini API"}}

node_user -->|"asks question"| node_ui
node_ui -->|"submits query"| node_engine
node_engine -->|"classifies intent"| node_router
node_engine -->|"loads unified data"| node_loader
node_loader -->|"reads CSVs"| node_dataset
node_engine -->|"dispatches trend"| node_revenue
node_revenue -->|"compares periods"| node_trend
node_engine -->|"dispatches product"| node_products
node_engine -->|"dispatches customer"| node_customers
node_engine -->|"extracts evidence"| node_evidence
node_engine -->|"synthesizes facts"| node_reasoner
node_reasoner -.->|"requests synthesis"| node_gemini
node_ui -->|"records decision"| node_audit
node_audit -->|"persists entry"| node_trail
node_investigator -->|"loads data"| node_loader
node_leakage -->|"loads data"| node_loader
node_decisions -->|"loads data"| node_loader

click node_ui "https://github.com/deepika-1020/leaklens/blob/main/app.py"
click node_engine "https://github.com/deepika-1020/leaklens/blob/main/src/leaklens_engine.py"
click node_router "https://github.com/deepika-1020/leaklens/blob/main/src/query_router.py"
click node_loader "https://github.com/deepika-1020/leaklens/blob/main/src/data_loader.py"
click node_dataset "https://github.com/deepika-1020/leaklens/tree/main/data"
click node_trend "https://github.com/deepika-1020/leaklens/blob/main/src/trend_analyzer.py"
click node_revenue "https://github.com/deepika-1020/leaklens/blob/main/src/revenue_investigator.py"
click node_products "https://github.com/deepika-1020/leaklens/blob/main/src/product_analyzer.py"
click node_customers "https://github.com/deepika-1020/leaklens/blob/main/src/customer_analyzer.py"
click node_evidence "https://github.com/deepika-1020/leaklens/blob/main/src/evidence_engine.py"
click node_investigator "https://github.com/deepika-1020/leaklens/blob/main/src/investigator.py"
click node_leakage "https://github.com/deepika-1020/leaklens/blob/main/src/leakage_detector.py"
click node_decisions "https://github.com/deepika-1020/leaklens/blob/main/src/decision_engine.py"
click node_reasoner "https://github.com/deepika-1020/leaklens/blob/main/src/reasoner.py"
click node_audit "https://github.com/deepika-1020/leaklens/blob/main/src/audit_logger.py"
click node_trail "https://github.com/deepika-1020/leaklens/blob/main/audit_trail.json"

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_ui,node_user toneBlue
class node_engine,node_router toneAmber
class node_loader,node_dataset,node_trend,node_revenue,node_products,node_customers,node_evidence,node_investigator,node_leakage,node_decisions,node_gemini toneMint
class node_reasoner,node_audit,node_trail toneRose
```

## Components

### User experience

- [Decision UI](https://github.com/deepika-1020/leaklens/blob/main/app.py): `app.py`

### Query orchestration

- [Investigation engine](https://github.com/deepika-1020/leaklens/blob/main/src/leaklens_engine.py): `src/leaklens_engine.py`
- [Intent router](https://github.com/deepika-1020/leaklens/blob/main/src/query_router.py): `src/query_router.py`

### Deterministic analytics

- [Data preparation](https://github.com/deepika-1020/leaklens/blob/main/src/data_loader.py): `src/data_loader.py`
- [Business CSVs](https://github.com/deepika-1020/leaklens/tree/main/data): `data`
- [Revenue trends](https://github.com/deepika-1020/leaklens/blob/main/src/trend_analyzer.py): `src/trend_analyzer.py`
- [Revenue investigation](https://github.com/deepika-1020/leaklens/blob/main/src/revenue_investigator.py): `src/revenue_investigator.py`
- [Product leakage](https://github.com/deepika-1020/leaklens/blob/main/src/product_analyzer.py): `src/product_analyzer.py`
- [Customer analysis](https://github.com/deepika-1020/leaklens/blob/main/src/customer_analyzer.py): `src/customer_analyzer.py`
- [Evidence extraction](https://github.com/deepika-1020/leaklens/blob/main/src/evidence_engine.py): `src/evidence_engine.py`
- [Investigation analysis](https://github.com/deepika-1020/leaklens/blob/main/src/investigator.py): `src/investigator.py`
- [Leakage detection](https://github.com/deepika-1020/leaklens/blob/main/src/leakage_detector.py): `src/leakage_detector.py`
- [Base decisions](https://github.com/deepika-1020/leaklens/blob/main/src/decision_engine.py): `src/decision_engine.py`

### Reasoning and governance

- [Grounded reasoner](https://github.com/deepika-1020/leaklens/blob/main/src/reasoner.py): `src/reasoner.py`
- [Audit logger](https://github.com/deepika-1020/leaklens/blob/main/src/audit_logger.py): `src/audit_logger.py`
- [Persistent audit trail](https://github.com/deepika-1020/leaklens/blob/main/audit_trail.json): `audit_trail.json`

### Other components

- **Business user**
- **Gemini API**

## Connections

- Business user → Decision UI: asks question (evidence: `README.md`)
- Decision UI → Investigation engine: submits query (evidence: `app.py`)
- Investigation engine → Intent router: classifies intent (evidence: `src/leaklens_engine.py`)
- Investigation engine → Data preparation: loads unified data (evidence: `src/leaklens_engine.py`)
- Data preparation → Business CSVs: reads CSVs (evidence: `src/data_loader.py`)
- Investigation engine → Revenue investigation: dispatches trend (evidence: `src/leaklens_engine.py`)
- Revenue investigation → Revenue trends: compares periods (evidence: `src/revenue_investigator.py`)
- Investigation engine → Product leakage: dispatches product (evidence: `src/leaklens_engine.py`)
- Investigation engine → Customer analysis: dispatches customer (evidence: `src/leaklens_engine.py`)
- Investigation engine → Evidence extraction: extracts evidence (evidence: `src/leaklens_engine.py`)
- Investigation engine → Grounded reasoner: synthesizes facts (evidence: `src/leaklens_engine.py`)
- Grounded reasoner → Gemini API: requests synthesis
- Decision UI → Audit logger: records decision (evidence: `app.py`)
- Audit logger → Persistent audit trail: persists entry (evidence: `src/audit_logger.py`)
- Investigation analysis → Data preparation: loads data (evidence: `src/investigator.py`)
- Leakage detection → Data preparation: loads data (evidence: `src/leakage_detector.py`)
- Base decisions → Data preparation: loads data (evidence: `src/decision_engine.py`)
