# javohir-g/gilamchi architecture

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

- Interactive diagram: https://gitdiagram.com/javohir-g/gilamchi
- Repository: https://github.com/javohir-g/gilamchi

## Overview

Gilamchi is a carpet-shop inventory and sales system: sellers authenticate, manage stock, build a basket and record sales; administrators manage branches, staff, finances and reporting. The frontend routes users to role-specific screens, while shared application state calls a REST API. The backend exposes domain routers backed by SQLAlchemy models and a configured database. Product image search and Telegram Web App entry are additional capabilities. Some frontend-to-backend links are shown as unverified because the excerpts do not demonstrate the HTTP wiring across both sides.

Main entry points: [`backend/app/main.py`](https://github.com/javohir-g/gilamchi/blob/main/backend/app/main.py) (API application), [`frontend/src/services/api.ts`](https://github.com/javohir-g/gilamchi/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/database.py`](https://github.com/javohir-g/gilamchi/blob/main/backend/app/database.py) (SQL database), [`frontend/src/app/App.tsx`](https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/App.tsx) (Role-based app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["Role-based app<br/>[App.tsx]"]
  node_seller_workflow["Selling and debts"]
  node_inventory_ui["Inventory management<br/>[Inventory.tsx]"]
  node_admin_ui["Admin operations"]
  node_app_state["Shared app state<br/>[AppContext.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_backend_app["API application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_products["Products and search<br/>[products.py]"]
  node_sales["Sales<br/>[sales.py]"]
  node_debts["Debts<br/>[debts.py]"]
  node_expenses["Expenses<br/>[expenses.py]"]
  node_collections["Collections<br/>[collections.py]"]
  node_branches["Branches<br/>[branches.py]"]
  node_staff_settings["Staff and settings"]
  node_telegram_api["Telegram enrollment<br/>[telegram.py]"]
end

subgraph group_data["Persistence and services"]
  node_database[("SQL database<br/>[database.py]")]
  node_product_model["Product records<br/>[product.py]"]
  node_embedding["Image embeddings<br/>[image_embedding.py]"]
end

subgraph group_integrations["External integrations"]
  node_telegram_bot["Telegram bot<br/>[bot_service.py]"]
end

node_seller(("Seller"))
node_administrator(("Administrator"))
node_telegram_user(("Telegram user"))

node_seller -->|"uses"| node_webapp
node_administrator -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_seller_workflow
node_webapp -->|"routes to"| node_admin_ui
node_webapp -.->|"routes to"| node_inventory_ui
node_seller_workflow -.->|"uses"| node_app_state
node_inventory_ui -->|"uses"| node_app_state
node_admin_ui -.->|"uses"| node_app_state
node_app_state -->|"calls"| node_api_client
node_api_client -.->|"HTTP requests"| node_auth
node_api_client -.->|"HTTP requests"| node_products
node_api_client -.->|"HTTP requests"| node_sales
node_api_client -.->|"HTTP requests"| node_debts
node_api_client -.->|"HTTP requests"| node_expenses
node_api_client -.->|"HTTP requests"| node_collections
node_api_client -.->|"HTTP requests"| node_branches
node_api_client -.->|"HTTP requests"| node_staff_settings
node_backend_app -->|"registers router"| node_auth
node_backend_app -->|"registers router"| node_branches
node_backend_app -->|"registers router"| node_products
node_backend_app -->|"registers router"| node_sales
node_backend_app -->|"registers router"| node_debts
node_backend_app -->|"registers router"| node_expenses
node_backend_app -->|"registers router"| node_collections
node_backend_app -->|"registers routers"| node_staff_settings
node_backend_app -->|"registers router"| node_telegram_api
node_backend_app -->|"creates tables"| node_database
node_backend_app -->|"starts bot"| node_telegram_bot
node_products -->|"queries"| node_database
node_sales -->|"queries"| node_database
node_debts -->|"queries"| node_database
node_expenses -->|"queries"| node_database
node_collections -->|"queries"| node_database
node_branches -->|"queries"| node_database
node_products -->|"uses model"| node_product_model
node_products -->|"extracts embeddings"| node_embedding
node_product_model -.->|"persisted by"| node_database
node_telegram_user -->|"starts chat"| node_telegram_bot
node_telegram_bot -.->|"supports enrollment"| node_telegram_api

click node_webapp "https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/App.tsx"
click node_seller_workflow "https://github.com/javohir-g/gilamchi/tree/main/frontend/src/app/components/seller"
click node_inventory_ui "https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/components/inventory/Inventory.tsx"
click node_admin_ui "https://github.com/javohir-g/gilamchi/tree/main/frontend/src/app/components/admin"
click node_app_state "https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/context/AppContext.tsx"
click node_api_client "https://github.com/javohir-g/gilamchi/blob/main/frontend/src/services/api.ts"
click node_backend_app "https://github.com/javohir-g/gilamchi/blob/main/backend/app/main.py"
click node_auth "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/auth.py"
click node_products "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/products.py"
click node_sales "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/sales.py"
click node_debts "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/debts.py"
click node_expenses "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/expenses.py"
click node_collections "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/collections.py"
click node_branches "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/branches.py"
click node_staff_settings "https://github.com/javohir-g/gilamchi/tree/main/backend/app/routers"
click node_telegram_api "https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/telegram.py"
click node_database "https://github.com/javohir-g/gilamchi/blob/main/backend/app/database.py"
click node_product_model "https://github.com/javohir-g/gilamchi/blob/main/backend/app/models/product.py"
click node_embedding "https://github.com/javohir-g/gilamchi/blob/main/backend/app/utils/image_embedding.py"
click node_telegram_bot "https://github.com/javohir-g/gilamchi/blob/main/backend/app/utils/bot_service.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_webapp,node_seller_workflow,node_inventory_ui,node_admin_ui,node_app_state,node_api_client,node_telegram_user toneBlue
class node_backend_app,node_auth,node_products,node_sales,node_debts,node_expenses,node_collections,node_branches,node_staff_settings,node_telegram_api toneAmber
class node_database,node_product_model,node_embedding toneMint
class node_telegram_bot toneRose
class node_seller,node_administrator toneIndigo
```

## Components

### Web application

- [Role-based app](https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Selling and debts](https://github.com/javohir-g/gilamchi/tree/main/frontend/src/app/components/seller): `frontend/src/app/components/seller`
- [Inventory management](https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/components/inventory/Inventory.tsx): `frontend/src/app/components/inventory/Inventory.tsx`
- [Admin operations](https://github.com/javohir-g/gilamchi/tree/main/frontend/src/app/components/admin): `frontend/src/app/components/admin`
- [Shared app state](https://github.com/javohir-g/gilamchi/blob/main/frontend/src/app/context/AppContext.tsx): `frontend/src/app/context/AppContext.tsx`
- [API client](https://github.com/javohir-g/gilamchi/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend API

- [API application](https://github.com/javohir-g/gilamchi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Products and search](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/products.py): `backend/app/routers/products.py`
- [Sales](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/sales.py): `backend/app/routers/sales.py`
- [Debts](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/debts.py): `backend/app/routers/debts.py`
- [Expenses](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/expenses.py): `backend/app/routers/expenses.py`
- [Collections](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/collections.py): `backend/app/routers/collections.py`
- [Branches](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/branches.py): `backend/app/routers/branches.py`
- [Staff and settings](https://github.com/javohir-g/gilamchi/tree/main/backend/app/routers): `backend/app/routers`
- [Telegram enrollment](https://github.com/javohir-g/gilamchi/blob/main/backend/app/routers/telegram.py): `backend/app/routers/telegram.py`

### Persistence and services

- [SQL database](https://github.com/javohir-g/gilamchi/blob/main/backend/app/database.py): `backend/app/database.py`
- [Product records](https://github.com/javohir-g/gilamchi/blob/main/backend/app/models/product.py): `backend/app/models/product.py`
- [Image embeddings](https://github.com/javohir-g/gilamchi/blob/main/backend/app/utils/image_embedding.py): `backend/app/utils/image_embedding.py`

### External integrations

- [Telegram bot](https://github.com/javohir-g/gilamchi/blob/main/backend/app/utils/bot_service.py): `backend/app/utils/bot_service.py`

### Other components

- **Seller**
- **Administrator**
- **Telegram user**

## Connections

- Seller → Role-based app: uses
- Administrator → Role-based app: uses
- Role-based app → Selling and debts: routes to (evidence: `frontend/src/app/App.tsx`)
- Role-based app → Admin operations: routes to (evidence: `frontend/src/app/App.tsx`)
- Role-based app → Inventory management: routes to (evidence: `frontend/src/app/App.tsx`)
- Selling and debts → Shared app state: uses (evidence: `frontend/src/app/components/seller/AddProduct.tsx`)
- Inventory management → Shared app state: uses (evidence: `frontend/src/app/components/inventory/Inventory.tsx`)
- Admin operations → Shared app state: uses (evidence: `frontend/src/app/components/admin/BranchDetail.tsx`)
- Shared app state → API client: calls (evidence: `frontend/src/app/context/AppContext.tsx`)
- API client → Authentication: HTTP requests
- API client → Products and search: HTTP requests
- API client → Sales: HTTP requests
- API client → Debts: HTTP requests
- API client → Expenses: HTTP requests
- API client → Collections: HTTP requests
- API client → Branches: HTTP requests
- API client → Staff and settings: HTTP requests
- API application → Authentication: registers router (evidence: `backend/app/main.py`)
- API application → Branches: registers router (evidence: `backend/app/main.py`)
- API application → Products and search: registers router (evidence: `backend/app/main.py`)
- API application → Sales: registers router (evidence: `backend/app/main.py`)
- API application → Debts: registers router (evidence: `backend/app/main.py`)
- API application → Expenses: registers router (evidence: `backend/app/main.py`)
- API application → Collections: registers router (evidence: `backend/app/main.py`)
- API application → Staff and settings: registers routers (evidence: `backend/app/main.py`)
- API application → Telegram enrollment: registers router (evidence: `backend/app/main.py`)
- API application → SQL database: creates tables (evidence: `backend/app/main.py`)
- API application → Telegram bot: starts bot (evidence: `backend/app/main.py`)
- Products and search → SQL database: queries (evidence: `backend/app/routers/products.py`)
- Sales → SQL database: queries (evidence: `backend/app/routers/sales.py`)
- Debts → SQL database: queries (evidence: `backend/app/routers/debts.py`)
- Expenses → SQL database: queries (evidence: `backend/app/routers/expenses.py`)
- Collections → SQL database: queries (evidence: `backend/app/routers/collections.py`)
- Branches → SQL database: queries (evidence: `backend/app/routers/branches.py`)
- Products and search → Product records: uses model (evidence: `backend/app/routers/products.py`)
- Products and search → Image embeddings: extracts embeddings (evidence: `backend/app/routers/products.py`)
- Product records → SQL database: persisted by
- Telegram user → Telegram bot: starts chat (evidence: `backend/app/utils/bot_service.py`)
- Telegram bot → Telegram enrollment: supports enrollment (evidence: `backend/app/utils/bot_service.py`)
