# saicharan67778/shrink-surveillance architecture

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

- Interactive diagram: https://gitdiagram.com/saicharan67778/shrink-surveillance
- Repository: https://github.com/saicharan67778/shrink-surveillance

## Overview

Shrink Surveillance is an inventory-shrinkage monitoring and investigation platform. Users view store-level metrics, inspect alerts, reconcile stock, and create investigations; operators can also review quarantined records, evaluation results, and detection settings. The documented backend combines reconciliation and rule-based detection with PostgreSQL, while a synthetic-data generator and loader support controlled evaluation. The frontend excerpt shows its API requests and user actions; backend routing and several evaluation, settings, and data-quality internals were not sampled, so those links rely on README documentation.

Main entry points: [`frontend/src/main.jsx`](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx) (Monitoring interface), [`backend/app/main.py`](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/main.py) (REST API), [`backend/app/db.py`](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/db.py) (Database access), [`backend/app/services/detection.py`](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/services/detection.py) (Anomaly detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Monitoring interface<br/>[main.jsx]"]
  node_dashboard["Dashboard<br/>[main.jsx]"]
  node_alerts["Alert management<br/>[main.jsx]"]
  node_reconciliation_ui["Reconciliation view<br/>[main.jsx]"]
  node_investigations_ui["Investigation view<br/>[main.jsx]"]
  node_quality_ui["Data quality view<br/>[main.jsx]"]
  node_evaluation_ui["Evaluation view<br/>[main.jsx]"]
  node_settings_ui["Detection settings view<br/>[main.jsx]"]
end

subgraph group_services["Backend services"]
  node_api["REST API<br/>[main.py]"]
  node_detection["Anomaly detection<br/>[detection.py]"]
  node_reconciliation["Stock reconciliation<br/>[reconciliation.py]"]
  node_evaluation["Detection evaluation"]
  node_settings["Store thresholds"]
  node_data_quality["Quarantine review"]
end

subgraph group_persistence["Data storage"]
  node_db_access["Database access<br/>[db.py]"]
  node_models["Table metadata<br/>[models.py]"]
  node_database[("Inventory database<br/>[schema.sql]")]
end

subgraph group_synthetic["Synthetic data"]
  node_generator["Synthetic data generator<br/>[generate.py]"]
  node_loader["CSV data loader<br/>[load.py]"]
end

node_user(("Operations user"))

node_user -->|"uses"| node_web
node_web -->|"requests data"| node_api
node_dashboard -->|"renders in"| node_web
node_alerts -->|"renders in"| node_web
node_reconciliation_ui -->|"renders in"| node_web
node_investigations_ui -->|"renders in"| node_web
node_quality_ui -->|"renders in"| node_web
node_evaluation_ui -->|"renders in"| node_web
node_settings_ui -->|"renders in"| node_web
node_api -->|"runs detection"| node_detection
node_api -->|"serves reconciliation"| node_reconciliation
node_api -->|"serves evaluation"| node_evaluation
node_api -->|"manages thresholds"| node_settings
node_api -->|"serves quarantine"| node_data_quality
node_detection -->|"reconciles counts"| node_reconciliation
node_detection -->|"queries and writes"| node_db_access
node_reconciliation -->|"queries movements"| node_db_access
node_db_access -->|"connects to"| node_database
node_models -->|"uses engine"| node_db_access
node_evaluation -->|"compares ground truth"| node_database
node_generator -->|"supplies CSVs"| node_loader
node_loader -->|"loads records"| node_database

click node_web "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_dashboard "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_alerts "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_reconciliation_ui "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_investigations_ui "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_quality_ui "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_evaluation_ui "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_settings_ui "https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx"
click node_api "https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/main.py"
click node_detection "https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/services/detection.py"
click node_reconciliation "https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/services/reconciliation.py"
click node_evaluation "https://github.com/saicharan67778/shrink-surveillance/tree/main/backend/app"
click node_settings "https://github.com/saicharan67778/shrink-surveillance/tree/main/backend/app"
click node_data_quality "https://github.com/saicharan67778/shrink-surveillance/tree/main/backend/app"
click node_db_access "https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/db.py"
click node_models "https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/models.py"
click node_database "https://github.com/saicharan67778/shrink-surveillance/blob/main/database/schema.sql"
click node_generator "https://github.com/saicharan67778/shrink-surveillance/blob/main/generator/generate.py"
click node_loader "https://github.com/saicharan67778/shrink-surveillance/blob/main/generator/load.py"

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_dashboard,node_alerts,node_reconciliation_ui,node_investigations_ui,node_quality_ui,node_evaluation_ui,node_settings_ui,node_user toneBlue
class node_api,node_detection,node_reconciliation,node_evaluation,node_settings,node_data_quality toneAmber
class node_db_access,node_models,node_database toneMint
class node_generator,node_loader toneRose
```

## Components

### User experience

- [Monitoring interface](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Dashboard](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Alert management](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Reconciliation view](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Investigation view](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Data quality view](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Evaluation view](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Detection settings view](https://github.com/saicharan67778/shrink-surveillance/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Backend services

- [REST API](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/main.py): `backend/app/main.py`
- [Anomaly detection](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/services/detection.py): `backend/app/services/detection.py`
- [Stock reconciliation](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/services/reconciliation.py): `backend/app/services/reconciliation.py`
- [Detection evaluation](https://github.com/saicharan67778/shrink-surveillance/tree/main/backend/app): `backend/app`
- [Store thresholds](https://github.com/saicharan67778/shrink-surveillance/tree/main/backend/app): `backend/app`
- [Quarantine review](https://github.com/saicharan67778/shrink-surveillance/tree/main/backend/app): `backend/app`

### Data storage

- [Database access](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/db.py): `backend/app/db.py`
- [Table metadata](https://github.com/saicharan67778/shrink-surveillance/blob/main/backend/app/models.py): `backend/app/models.py`
- [Inventory database](https://github.com/saicharan67778/shrink-surveillance/blob/main/database/schema.sql): `database/schema.sql`

### Synthetic data

- [Synthetic data generator](https://github.com/saicharan67778/shrink-surveillance/blob/main/generator/generate.py): `generator/generate.py`
- [CSV data loader](https://github.com/saicharan67778/shrink-surveillance/blob/main/generator/load.py): `generator/load.py`

### Other components

- **Operations user**

## Connections

- Operations user → Monitoring interface: uses (evidence: `README.md`)
- Monitoring interface → REST API: requests data (evidence: `frontend/src/main.jsx`)
- Dashboard → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- Alert management → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- Reconciliation view → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- Investigation view → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- Data quality view → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- Evaluation view → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- Detection settings view → Monitoring interface: renders in (evidence: `frontend/src/main.jsx`)
- REST API → Anomaly detection: runs detection (evidence: `README.md`)
- REST API → Stock reconciliation: serves reconciliation (evidence: `README.md`)
- REST API → Detection evaluation: serves evaluation (evidence: `README.md`)
- REST API → Store thresholds: manages thresholds (evidence: `README.md`)
- REST API → Quarantine review: serves quarantine (evidence: `README.md`)
- Anomaly detection → Stock reconciliation: reconciles counts (evidence: `backend/app/services/detection.py`)
- Anomaly detection → Database access: queries and writes (evidence: `backend/app/services/detection.py`)
- Stock reconciliation → Database access: queries movements (evidence: `backend/app/services/reconciliation.py`)
- Database access → Inventory database: connects to (evidence: `README.md`)
- Table metadata → Database access: uses engine (evidence: `backend/app/models.py`)
- Detection evaluation → Inventory database: compares ground truth (evidence: `README.md`)
- Synthetic data generator → CSV data loader: supplies CSVs (evidence: `README.md`)
- CSV data loader → Inventory database: loads records (evidence: `generator/load.py`)
