# pkiran2979/warehouse-ops architecture

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

- Interactive diagram: https://gitdiagram.com/pkiran2979/warehouse-ops
- Repository: https://github.com/pkiran2979/warehouse-ops

## Overview

Warehouse Ops is a Flask warehouse-management app for construction materials. Store staff maintain materials, receive and issue stock, and record cycle-count variances; stock is represented by ledger movements, while users can view inventory and export data. A separate document workflow uploads files and indexes searchable SOPs. Authentication and role checks govern access. The route and model implementation is concentrated in app.py; the excerpts show receiving, issuing, authentication, and document indexing, but not every route. Other capabilities and their relationships are retained where documented in the README.

Main entry points: [`app.py`](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py) (Flask routes), [`rag.py`](https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py) (Document retrieval), [`static/app.js`](https://github.com/pkiran2979/warehouse-ops/blob/main/static/app.js) (Browser interactions), [`templates`](https://github.com/pkiran2979/warehouse-ops/tree/main/templates) (Jinja pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inventory["Inventory Operations"]
  node_routes["Flask routes<br/>[app.py]"]
  node_materials["Material master<br/>[app.py]"]
  node_receiving["Receiving and putaway<br/>[app.py]"]
  node_issuing["Issue to site<br/>[app.py]"]
  node_cycle_count["Cycle counts<br/>[app.py]"]
  node_ledger[("Stock ledger<br/>[app.py]")]
  node_stock_views["Stock views<br/>[app.py]"]
  node_excel["Excel transfer<br/>[app.py]"]
  node_relational_db[("SQL database<br/>[app.py]")]
end

subgraph group_knowledge["Documents and Search"]
  node_documents["Document management<br/>[app.py]"]
  node_text_extract["Text extraction<br/>[rag.py]"]
  node_retrieval["Document retrieval<br/>[rag.py]"]
  node_document_index[("Document index<br/>[rag.py]")]
  node_chroma[("Chroma")]
  node_keyword_search["Keyword fallback<br/>[rag.py]"]
end

subgraph group_access["Access and Users"]
  node_auth["Authentication and roles<br/>[app.py]"]
  node_user_admin["User management<br/>[app.py]"]
end

subgraph group_interface["Web Interface"]
  node_pages["Jinja pages"]
  node_browser_helpers["Browser interactions<br/>[app.js]"]
end

node_staff(("Warehouse users"))

node_staff -->|"uses"| node_routes
node_routes -->|"checks access"| node_auth
node_routes -->|"renders"| node_pages
node_routes -->|"manages"| node_materials
node_routes -->|"handles"| node_receiving
node_routes -->|"handles"| node_issuing
node_routes -->|"handles"| node_cycle_count
node_routes -->|"handles"| node_excel
node_routes -->|"handles"| node_documents
node_routes -->|"handles"| node_user_admin
node_routes -->|"provides"| node_stock_views
node_receiving -->|"records movement"| node_ledger
node_issuing -->|"records movement"| node_ledger
node_cycle_count -->|"posts variance"| node_ledger
node_ledger -->|"persists in"| node_relational_db
node_stock_views -->|"reads stock"| node_relational_db
node_excel -->|"imports and exports"| node_relational_db
node_documents -->|"extracts text"| node_text_extract
node_documents -->|"indexes text"| node_retrieval
node_documents -->|"searches"| node_retrieval
node_retrieval -->|"stores chunks"| node_document_index
node_retrieval -.->|"uses when available"| node_chroma
node_retrieval -->|"falls back to"| node_keyword_search
node_browser_helpers -.->|"supports interaction"| node_staff

click node_routes "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_materials "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_receiving "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_issuing "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_cycle_count "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_ledger "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_stock_views "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_excel "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_relational_db "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_documents "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_text_extract "https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py"
click node_retrieval "https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py"
click node_document_index "https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py"
click node_keyword_search "https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py"
click node_auth "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_user_admin "https://github.com/pkiran2979/warehouse-ops/blob/main/app.py"
click node_pages "https://github.com/pkiran2979/warehouse-ops/tree/main/templates"
click node_browser_helpers "https://github.com/pkiran2979/warehouse-ops/blob/main/static/app.js"

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_routes,node_materials,node_receiving,node_issuing,node_cycle_count,node_ledger,node_stock_views,node_excel,node_relational_db,node_staff toneBlue
class node_documents,node_text_extract,node_retrieval,node_document_index,node_chroma,node_keyword_search toneAmber
class node_auth,node_user_admin toneMint
class node_pages,node_browser_helpers toneRose
```

## Components

### Inventory Operations

- [Flask routes](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Material master](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Receiving and putaway](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Issue to site](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Cycle counts](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Stock ledger](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Stock views](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Excel transfer](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [SQL database](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`

### Documents and Search

- [Document management](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [Text extraction](https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py): `rag.py`
- [Document retrieval](https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py): `rag.py`
- [Document index](https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py): `rag.py`
- **Chroma**
- [Keyword fallback](https://github.com/pkiran2979/warehouse-ops/blob/main/rag.py): `rag.py`

### Access and Users

- [Authentication and roles](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`
- [User management](https://github.com/pkiran2979/warehouse-ops/blob/main/app.py): `app.py`

### Web Interface

- [Jinja pages](https://github.com/pkiran2979/warehouse-ops/tree/main/templates): `templates`
- [Browser interactions](https://github.com/pkiran2979/warehouse-ops/blob/main/static/app.js): `static/app.js`

### Other components

- **Warehouse users**

## Connections

- Warehouse users → Flask routes: uses (evidence: `README.md`)
- Flask routes → Authentication and roles: checks access (evidence: `app.py`)
- Flask routes → Jinja pages: renders (evidence: `README.md`)
- Flask routes → Material master: manages (evidence: `README.md`)
- Flask routes → Receiving and putaway: handles (evidence: `README.md`)
- Flask routes → Issue to site: handles (evidence: `README.md`)
- Flask routes → Cycle counts: handles (evidence: `README.md`)
- Flask routes → Excel transfer: handles (evidence: `README.md`)
- Flask routes → Document management: handles (evidence: `app.py`)
- Flask routes → User management: handles (evidence: `app.py`)
- Flask routes → Stock views: provides (evidence: `README.md`)
- Receiving and putaway → Stock ledger: records movement (evidence: `app.py`)
- Issue to site → Stock ledger: records movement (evidence: `app.py`)
- Cycle counts → Stock ledger: posts variance (evidence: `README.md`)
- Stock ledger → SQL database: persists in (evidence: `README.md`)
- Stock views → SQL database: reads stock (evidence: `README.md`)
- Excel transfer → SQL database: imports and exports (evidence: `README.md`)
- Document management → Text extraction: extracts text (evidence: `app.py`)
- Document management → Document retrieval: indexes text (evidence: `app.py`)
- Document management → Document retrieval: searches (evidence: `README.md`)
- Document retrieval → Document index: stores chunks (evidence: `rag.py`)
- Document retrieval → Chroma: uses when available (evidence: `rag.py`)
- Document retrieval → Keyword fallback: falls back to (evidence: `rag.py`)
- Browser interactions → Warehouse users: supports interaction