# santhosh790/ecomsenseai architecture

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

- Interactive diagram: https://gitdiagram.com/santhosh790/ecomsenseai
- Repository: https://github.com/santhosh790/ecomsenseai

## Overview

#### Purpose and entry point
ecomSenseAI is a Streamlit-based document-processing application that extracts vegetable items and quantities from PDF, image, and Excel orders, lets users validate results, and saves date-scoped order outputs. The composition/UI entry point is `ecomSenseAI.py`; domain and service layers support its upload-to-confirm workflow.

#### Domain model and catalog
Extracted items are represented as typed domain records, including detection status and confidence, in `domain/models.py`. Vegetable normalization and lookup are driven by catalog/alias data in `data/vegetables.json` and `data/aliases.json`, accessed through `infrastructure/vegetable_catalog_repository.py`. This catalog boundary separates source-document wording, OCR noise, and canonical output names.

#### Extraction pipeline
`application/extraction_service.py` is the central parsing and decision layer. It selects/handles document text formats, identifies item/quantity candidates, performs fuzzy catalog matching, and applies confidence/status policy. It produces domain detections rather than coupling parser logic directly to the Streamlit UI. Client- or supplier-specific interpretation is supported through data such as `data/clients.json`.

#### Document and OCR ingress
Document-specific text acquisition is isolated from extraction rules. `infrastructure/document_readers.py` handles PDF/Excel-style input reading, while `infrastructure/ocr_engine.py` handles image preprocessing and OCR. The OCR engine prefers PaddleOCR with OpenCV preprocessing and falls back to Tesseract; Tesseract additionally requires a host-installed binary. Extracted text is returned to the application layer for parsing and user preview.

#### Validation and order lifecycle
The primary control flow is: upload → read/OCR → extract detections → user validation/editing → confirm → persist and optionally publish. `ecomSenseAI.py` presents confidence controls and review states so low-confidence detections remain human-verifiable. `application/reporting_service.py` forms individual and consolidated order views, while `application/vegetable_detection_service.py` supports detection-oriented application operations.

#### Persistence, reporting, and saved-order boundaries
Confirmed rows are saved locally as dated CSV outputs and can be reloaded/revalidated by date and source file. `infrastructure/persistence_service.py` owns this storage boundary; `infrastructure/assets_service.py` supports stored upload/original-asset handling. Consolidation aggregates quantities across confirmed files for a selected date rather than treating each upload as an isolated final report.

#### External integrations and deployment runtime
Google Sheets publishing is optional and isolated in `infrastructure/google_sheets_service.py`, using Streamlit secrets for a GCP service account and target worksheet. Address-related data/services are separate (`infrastructure/address_service.py`, `data/addresses.json`), likely supporting order/report organization. Python dependencies are declared in `requirements.txt`; deployment-level system OCR/font requirements are captured in `packages.txt`, with Streamlit Cloud as the documented hosting target.

Main entry points: [`ecomSenseAI.py`](https://github.com/santhosh790/ecomsenseai/blob/main/ecomSenseAI.py) (ecomSenseAI), [`application/extraction_service.py`](https://github.com/santhosh790/ecomsenseai/blob/main/application/extraction_service.py) (Extraction service), [`infrastructure/vegetable_catalog_repository.py`](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/vegetable_catalog_repository.py) (Vegetable catalog), [`infrastructure/ocr_engine.py`](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/ocr_engine.py) (OCR engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit UI"]
  node_streamlit_app["ecomSenseAI<br/>Streamlit entry point<br/>[ecomSenseAI.py]"]
  node_source_documents["Uploaded orders<br/>PDF, image, Excel"]
end

subgraph group_application["Application services"]
  node_domain_models["Detection records<br/>domain model<br/>[models.py]"]
  node_extraction_service["Extraction service<br/>parsing and decision layer"]
  node_detection_service["Detection service<br/>application service"]
  node_reporting_service["Reporting service<br/>application service"]
end

subgraph group_infrastructure["Infrastructure and data"]
  node_document_readers["Document readers<br/>PDF and Excel reader"]
  node_ocr_engine["OCR engine<br/>image text extraction<br/>[ocr_engine.py]"]
  node_catalog_repository["Vegetable catalog<br/>catalog repository"]
  node_vegetables_data[("Vegetable catalog data<br/>JSON data<br/>[vegetables.json]")]
  node_aliases_data[("Vegetable aliases<br/>JSON data<br/>[aliases.json]")]
  node_clients_data[("Client rules data<br/>JSON data<br/>[clients.json]")]
  node_persistence_service[("Order persistence<br/>dated CSV storage")]
  node_assets_service["Asset storage<br/>upload asset service<br/>[assets_service.py]"]
  node_google_sheets["Google Sheets publisher<br/>optional integration"]
  node_address_service["Address service<br/>address lookup<br/>[address_service.py]"]
  node_addresses_data[("Address data<br/>JSON data<br/>[addresses.json]")]
  node_runtime_requirements["Deployment requirements<br/>Python and system dependencies<br/>[requirements.txt]"]
end

node_source_documents -->|"upload"| node_streamlit_app
node_streamlit_app -->|"PDF/Excel text"| node_document_readers
node_streamlit_app -->|"image text"| node_ocr_engine
node_document_readers -->|"text"| node_extraction_service
node_ocr_engine -->|"OCR text"| node_extraction_service
node_extraction_service -->|"fuzzy lookup"| node_catalog_repository
node_catalog_repository -->|"canonical names"| node_vegetables_data
node_catalog_repository -->|"aliases"| node_aliases_data
node_extraction_service -->|"client interpretation"| node_clients_data
node_extraction_service -->|"detections"| node_domain_models
node_domain_models -->|"review and edit"| node_streamlit_app
node_streamlit_app -->|"detection operations"| node_detection_service
node_streamlit_app -->|"confirm and reload"| node_persistence_service
node_streamlit_app -->|"store originals"| node_assets_service
node_persistence_service -->|"dated confirmed orders"| node_reporting_service
node_reporting_service -->|"order views"| node_streamlit_app
node_streamlit_app -.->|"optional publish"| node_google_sheets
node_streamlit_app -->|"address organization"| node_address_service
node_address_service -->|"lookup"| node_addresses_data
node_runtime_requirements -.->|"OCR dependencies"| node_ocr_engine

click node_streamlit_app "https://github.com/santhosh790/ecomsenseai/blob/main/ecomSenseAI.py"
click node_domain_models "https://github.com/santhosh790/ecomsenseai/blob/main/domain/models.py"
click node_extraction_service "https://github.com/santhosh790/ecomsenseai/blob/main/application/extraction_service.py"
click node_detection_service "https://github.com/santhosh790/ecomsenseai/blob/main/application/vegetable_detection_service.py"
click node_reporting_service "https://github.com/santhosh790/ecomsenseai/blob/main/application/reporting_service.py"
click node_document_readers "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/document_readers.py"
click node_ocr_engine "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/ocr_engine.py"
click node_catalog_repository "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/vegetable_catalog_repository.py"
click node_vegetables_data "https://github.com/santhosh790/ecomsenseai/blob/main/data/vegetables.json"
click node_aliases_data "https://github.com/santhosh790/ecomsenseai/blob/main/data/aliases.json"
click node_clients_data "https://github.com/santhosh790/ecomsenseai/blob/main/data/clients.json"
click node_persistence_service "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/persistence_service.py"
click node_assets_service "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/assets_service.py"
click node_google_sheets "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/google_sheets_service.py"
click node_address_service "https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/address_service.py"
click node_addresses_data "https://github.com/santhosh790/ecomsenseai/blob/main/data/addresses.json"
click node_runtime_requirements "https://github.com/santhosh790/ecomsenseai/blob/main/requirements.txt"

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_streamlit_app,node_source_documents toneBlue
class node_domain_models,node_extraction_service,node_detection_service,node_reporting_service toneAmber
class node_document_readers,node_ocr_engine,node_catalog_repository,node_vegetables_data,node_aliases_data,node_clients_data,node_persistence_service,node_assets_service,node_google_sheets,node_address_service,node_addresses_data,node_runtime_requirements toneMint
```

## Components

### Streamlit UI

- [ecomSenseAI](https://github.com/santhosh790/ecomsenseai/blob/main/ecomSenseAI.py): Streamlit entry point · Runs the upload-to-confirm workflow. · `ecomSenseAI.py`
- **Uploaded orders**: PDF, image, Excel

### Application services

- [Detection records](https://github.com/santhosh790/ecomsenseai/blob/main/domain/models.py): domain model · Typed items include status and confidence. · `domain/models.py`
- [Extraction service](https://github.com/santhosh790/ecomsenseai/blob/main/application/extraction_service.py): parsing and decision layer · Finds item quantities, matches catalog names, and assigns confidence. · `application/extraction_service.py`
- [Detection service](https://github.com/santhosh790/ecomsenseai/blob/main/application/vegetable_detection_service.py): application service · `application/vegetable_detection_service.py`
- [Reporting service](https://github.com/santhosh790/ecomsenseai/blob/main/application/reporting_service.py): application service · Builds individual and consolidated order views. · `application/reporting_service.py`

### Infrastructure and data

- [Document readers](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/document_readers.py): PDF and Excel reader · `infrastructure/document_readers.py`
- [OCR engine](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/ocr_engine.py): image text extraction · OpenCV preprocessing with PaddleOCR and Tesseract fallback. · `infrastructure/ocr_engine.py`
- [Vegetable catalog](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/vegetable_catalog_repository.py): catalog repository · Normalizes source wording to canonical vegetable names. · `infrastructure/vegetable_catalog_repository.py`
- [Vegetable catalog data](https://github.com/santhosh790/ecomsenseai/blob/main/data/vegetables.json): JSON data · `data/vegetables.json`
- [Vegetable aliases](https://github.com/santhosh790/ecomsenseai/blob/main/data/aliases.json): JSON data · `data/aliases.json`
- [Client rules data](https://github.com/santhosh790/ecomsenseai/blob/main/data/clients.json): JSON data · `data/clients.json`
- [Order persistence](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/persistence_service.py): dated CSV storage · Saves, reloads, and revalidates confirmed orders. · `infrastructure/persistence_service.py`
- [Asset storage](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/assets_service.py): upload asset service · `infrastructure/assets_service.py`
- [Google Sheets publisher](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/google_sheets_service.py): optional integration · Publishes confirmed outputs using Streamlit secrets. · `infrastructure/google_sheets_service.py`
- [Address service](https://github.com/santhosh790/ecomsenseai/blob/main/infrastructure/address_service.py): address lookup · `infrastructure/address_service.py`
- [Address data](https://github.com/santhosh790/ecomsenseai/blob/main/data/addresses.json): JSON data · `data/addresses.json`
- [Deployment requirements](https://github.com/santhosh790/ecomsenseai/blob/main/requirements.txt): Python and system dependencies · Includes OCR and font requirements for Streamlit Cloud. · `requirements.txt`

## Connections

- Uploaded orders → ecomSenseAI: upload
- ecomSenseAI → Document readers: PDF/Excel text
- ecomSenseAI → OCR engine: image text
- Document readers → Extraction service: text
- OCR engine → Extraction service: OCR text
- Extraction service → Vegetable catalog: fuzzy lookup
- Vegetable catalog → Vegetable catalog data: canonical names
- Vegetable catalog → Vegetable aliases: aliases
- Extraction service → Client rules data: client interpretation
- Extraction service → Detection records: detections
- Detection records → ecomSenseAI: review and edit
- ecomSenseAI → Detection service: detection operations
- ecomSenseAI → Order persistence: confirm and reload
- ecomSenseAI → Asset storage: store originals
- Order persistence → Reporting service: dated confirmed orders
- Reporting service → ecomSenseAI: order views
- ecomSenseAI → Google Sheets publisher: optional publish
- ecomSenseAI → Address service: address organization
- Address service → Address data: lookup
- Deployment requirements → OCR engine: OCR dependencies