# layvanntha-glitch/wheelroadshow_bot architecture

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

- Interactive diagram: https://gitdiagram.com/layvanntha-glitch/wheelroadshow_bot
- Repository: https://github.com/layvanntha-glitch/wheelroadshow_bot

## Overview

WheelRoadShow is a workshop-management system with an admin console and a shared customer storefront available on the web or in Telegram. Customers browse products, book service, place orders, and track them; staff manage counter sales, inventory, jobs, returns, expenses, reports, and team access. Both surfaces use a typed API backed by SQLite, with Telegram messaging and live events as supporting capabilities. Edges reflect README statements and shown imports/calls; several README-documented subsystems have unsampled implementation details.

Main entry points: [`server/services/orders.service.ts`](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/orders.service.ts) (Orders and sales), [`server/db/repos/crm.repo.ts`](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/crm.repo.ts) (Customer and order data), [`server/routes`](https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/server/routes) (Express routes), [`server/services/jobs.service.ts`](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/jobs.service.ts) (Service bay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_adminui["Admin console"]
  node_storefront["Storefront"]
  node_apiendpoints["Typed endpoints<br/>[endpoints.ts]"]
  node_apiclient["Fetch client<br/>[client.ts]"]
end

subgraph group_api["HTTP API"]
  node_routes["Express routes"]
  node_authroutes["Authentication routes<br/>[auth.routes.ts]"]
end

subgraph group_domain["Business services"]
  node_authsvc["Authentication<br/>[auth.service.ts]"]
  node_inventory["Stock integrity"]
  node_orders["Orders and sales<br/>[orders.service.ts]"]
  node_jobs["Service bay<br/>[jobs.service.ts]"]
  node_reports["Reports<br/>[reports.service.ts]"]
  node_returns["Returns<br/>[returns.service.ts]"]
  node_telegramupdates["Telegram updates"]
end

subgraph group_data["Persistence"]
  node_sqlite[("SQLite database<br/>[client.ts]")]
  node_crmrepo["Customer and order data<br/>[crm.repo.ts]"]
  node_productrepo["Product data<br/>[products.repo.ts]"]
  node_jobrepo["Job data<br/>[jobs.repo.ts]"]
  node_transactionsrepo["Transaction data"]
end

subgraph group_integration["Shared runtime"]
  node_events["Live event bus<br/>[events.ts]"]
  node_telegram["Telegram client<br/>[telegram.ts]"]
  node_contracts["Shared contracts<br/>[types.ts]"]
end

node_customer(("Customer"))
node_staff(("Shop staff"))
node_telegramservice{{"Telegram platform"}}

node_customer -->|"browses and books"| node_storefront
node_staff -->|"runs workshop"| node_adminui
node_storefront -->|"requests data"| node_apiendpoints
node_adminui -.->|"uses API"| node_apiendpoints
node_apiendpoints -->|"calls"| node_apiclient
node_apiclient -.->|"sends HTTP"| node_routes
node_routes -->|"delegates auth"| node_authsvc
node_authroutes -->|"calls"| node_authsvc
node_authsvc -->|"reads and updates"| node_crmrepo
node_authsvc -.->|"issues signed sessions"| node_sqlite
node_routes -->|"delegates stock"| node_inventory
node_routes -->|"delegates orders"| node_orders
node_routes -->|"changes job status"| node_jobs
node_jobs -->|"reads and writes jobs"| node_jobrepo
node_jobs -->|"completes with stock"| node_inventory
node_jobs -->|"records customer messages"| node_crmrepo
node_orders -->|"reads and writes orders"| node_crmrepo
node_orders -->|"reads product prices"| node_productrepo
node_orders -->|"draws down stock"| node_inventory
node_reports -->|"reads sales data"| node_crmrepo
node_reports -->|"reads product data"| node_productrepo
node_reports -->|"reads transactions"| node_transactionsrepo
node_inventory -.->|"updates stock"| node_productrepo
node_crmrepo -->|"executes SQL"| node_sqlite
node_productrepo -->|"executes SQL"| node_sqlite
node_jobrepo -->|"executes SQL"| node_sqlite
node_events -->|"streams updates"| node_customer
node_orders -.->|"broadcasts changes"| node_events
node_jobs -->|"broadcasts changes"| node_events
node_telegramupdates -->|"handles conversations"| node_crmrepo
node_telegramupdates -->|"processes order updates"| node_orders
node_telegramupdates -->|"sends notifications"| node_telegram
node_telegram -->|"calls bot API"| node_telegramservice
node_storefront -->|"runs as Mini App"| node_telegramservice
node_contracts -->|"defines shared types"| node_adminui
node_contracts -->|"defines shared types"| node_storefront

click node_adminui "https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/src/admin"
click node_storefront "https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/src/telegram"
click node_apiendpoints "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/src/api/endpoints.ts"
click node_apiclient "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/src/api/client.ts"
click node_routes "https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/server/routes"
click node_authroutes "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/routes/auth.routes.ts"
click node_authsvc "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/auth.service.ts"
click node_inventory "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/inventory.service.ts"
click node_orders "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/orders.service.ts"
click node_jobs "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/jobs.service.ts"
click node_reports "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/reports.service.ts"
click node_returns "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/returns.service.ts"
click node_telegramupdates "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/telegram-updates.service.ts"
click node_sqlite "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/client.ts"
click node_crmrepo "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/crm.repo.ts"
click node_productrepo "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/products.repo.ts"
click node_jobrepo "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/jobs.repo.ts"
click node_transactionsrepo "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/transactions.repo.ts"
click node_events "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/lib/events.ts"
click node_telegram "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/lib/telegram.ts"
click node_contracts "https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/shared/types.ts"

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_adminui,node_storefront,node_apiendpoints,node_apiclient toneBlue
class node_routes,node_authroutes toneAmber
class node_authsvc,node_inventory,node_orders,node_jobs,node_reports,node_returns,node_telegramupdates toneMint
class node_sqlite,node_crmrepo,node_productrepo,node_jobrepo,node_transactionsrepo toneRose
class node_events,node_telegram,node_contracts,node_customer,node_staff,node_telegramservice toneIndigo
```

## Components

### User surfaces

- [Admin console](https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/src/admin): `src/admin`
- [Storefront](https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/src/telegram): `src/telegram`
- [Typed endpoints](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/src/api/endpoints.ts): `src/api/endpoints.ts`
- [Fetch client](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/src/api/client.ts): `src/api/client.ts`

### HTTP API

- [Express routes](https://github.com/layvanntha-glitch/wheelroadshow_bot/tree/main/server/routes): `server/routes`
- [Authentication routes](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/routes/auth.routes.ts): `server/routes/auth.routes.ts`

### Business services

- [Authentication](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/auth.service.ts): `server/services/auth.service.ts`
- [Stock integrity](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/inventory.service.ts): `server/services/inventory.service.ts`
- [Orders and sales](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/orders.service.ts): `server/services/orders.service.ts`
- [Service bay](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/jobs.service.ts): `server/services/jobs.service.ts`
- [Reports](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/reports.service.ts): `server/services/reports.service.ts`
- [Returns](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/returns.service.ts): `server/services/returns.service.ts`
- [Telegram updates](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/services/telegram-updates.service.ts): `server/services/telegram-updates.service.ts`

### Persistence

- [SQLite database](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/client.ts): `server/db/client.ts`
- [Customer and order data](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/crm.repo.ts): `server/db/repos/crm.repo.ts`
- [Product data](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/products.repo.ts): `server/db/repos/products.repo.ts`
- [Job data](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/jobs.repo.ts): `server/db/repos/jobs.repo.ts`
- [Transaction data](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/db/repos/transactions.repo.ts): `server/db/repos/transactions.repo.ts`

### Shared runtime

- [Live event bus](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/lib/events.ts): `server/lib/events.ts`
- [Telegram client](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/server/lib/telegram.ts): `server/lib/telegram.ts`
- [Shared contracts](https://github.com/layvanntha-glitch/wheelroadshow_bot/blob/main/shared/types.ts): `shared/types.ts`

### Other components

- **Customer**
- **Shop staff**
- **Telegram platform**

## Connections

- Customer → Storefront: browses and books
- Shop staff → Admin console: runs workshop
- Storefront → Typed endpoints: requests data (evidence: `src/telegram/MiniApp.tsx`)
- Admin console → Typed endpoints: uses API (evidence: `src/admin/JobsPage.tsx`)
- Typed endpoints → Fetch client: calls (evidence: `src/api/endpoints.ts`)
- Fetch client → Express routes: sends HTTP
- Express routes → Authentication: delegates auth (evidence: `server/routes/auth.routes.ts`)
- Authentication routes → Authentication: calls (evidence: `server/routes/auth.routes.ts`)
- Authentication → Customer and order data: reads and updates (evidence: `server/services/auth.service.ts`)
- Authentication → SQLite database: issues signed sessions
- Express routes → Stock integrity: delegates stock (evidence: `server/routes/catalog.routes.ts`)
- Express routes → Orders and sales: delegates orders (evidence: `server/routes/crm.routes.ts`)
- Express routes → Service bay: changes job status (evidence: `server/routes/jobs.routes.ts`)
- Service bay → Job data: reads and writes jobs (evidence: `server/services/jobs.service.ts`)
- Service bay → Stock integrity: completes with stock (evidence: `server/services/jobs.service.ts`)
- Service bay → Customer and order data: records customer messages (evidence: `server/services/jobs.service.ts`)
- Orders and sales → Customer and order data: reads and writes orders (evidence: `server/services/orders.service.ts`)
- Orders and sales → Product data: reads product prices (evidence: `server/services/orders.service.ts`)
- Orders and sales → Stock integrity: draws down stock (evidence: `server/services/orders.service.ts`)
- Reports → Customer and order data: reads sales data (evidence: `server/services/reports.service.ts`)
- Reports → Product data: reads product data (evidence: `server/services/reports.service.ts`)
- Reports → Transaction data: reads transactions (evidence: `server/services/reports.service.ts`)
- Stock integrity → Product data: updates stock
- Customer and order data → SQLite database: executes SQL (evidence: `server/db/repos/crm.repo.ts`)
- Product data → SQLite database: executes SQL (evidence: `server/db/repos/products.repo.ts`)
- Job data → SQLite database: executes SQL (evidence: `server/db/repos/jobs.repo.ts`)
- Live event bus → Customer: streams updates
- Orders and sales → Live event bus: broadcasts changes (evidence: `server/services/orders.service.ts`)
- Service bay → Live event bus: broadcasts changes (evidence: `server/services/jobs.service.ts`)
- Telegram updates → Customer and order data: handles conversations (evidence: `server/services/telegram-updates.service.ts`)
- Telegram updates → Orders and sales: processes order updates (evidence: `server/services/telegram-updates.service.ts`)
- Telegram updates → Telegram client: sends notifications (evidence: `server/services/telegram-updates.service.ts`)
- Telegram client → Telegram platform: calls bot API (evidence: `server/lib/telegram.ts`)
- Storefront → Telegram platform: runs as Mini App
- Shared contracts → Admin console: defines shared types
- Shared contracts → Storefront: defines shared types