# ziehna/clothcraftv3 architecture

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

- Interactive diagram: https://gitdiagram.com/ziehna/clothcraftv3
- Repository: https://github.com/ziehna/clothcraftv3

## Overview

ClothCraft is a garment storefront and operations system built around an Odoo module, with a browser frontend and a Python API service. Customers browse products, customize designs, maintain a cart, and place or track orders; staff manage stock, suppliers, and orders. Administrators also use DSS forecasting and an assistant. Odoo owns business records and validates cart operations; the DSS engine derives forecasts, restock recommendations, alerts, and health results. The graph combines documented capabilities with sampled imports and calls; some unsampled subsystem links are omitted rather than inferred.

Main entry points: [`frontend/src/pages/Checkout.tsx`](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/pages/Checkout.tsx) (Shop and checkout), [`backend/app/main.py`](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/main.py) (API application), [`backend/app/jev_forecast_routes.py`](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/jev_forecast_routes.py) (DSS routes), [`addons/clothcraft_dss/engine/bundle.py`](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/bundle.py) (Analysis bundle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_store["Customer storefront"]
  node_storefront["Shop and checkout<br/>[Checkout.tsx]"]
  node_editor["Design editor<br/>[EditorStage.tsx]"]
  node_browser_api["API client<br/>[client.ts]"]
end

subgraph group_service["API service"]
  node_api["API application<br/>[main.py]"]
  node_cart_api["Cart routes<br/>[cart_routes.py]"]
  node_odoo_client["Odoo facade<br/>[odoo.py]"]
  node_chat_routes["Assistant routes<br/>[chat_routes.py]"]
  node_dss_routes["DSS routes"]
end

subgraph group_odoo["Odoo commerce"]
  node_shop_models[("Commerce models<br/>[sale_order.py]")]
  node_design_pricing["Design pricing<br/>[design_fee.py]"]
  node_staff_ops["Staff operations<br/>[stock_move.py]"]
end

subgraph group_dss["Decision support"]
  node_dss_api["DSS Odoo API<br/>[api_dss.py]"]
  node_dss_run[("DSS run storage<br/>[dss_run.py]")]
  node_dss_bundle["Analysis bundle<br/>[bundle.py]"]
  node_dss_transform["Canonical transforms<br/>[transform.py]"]
  node_dss_forecast["Demand forecasting<br/>[forecast.py]"]
  node_ai_forecast["AI forecast integration<br/>[api_dss_ai.py]"]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin workspace<br/>[AdminApp.tsx]"]
  node_chat_ui["Admin assistant UI<br/>[useAssistant.ts]"]
  node_dss_ui["DSS workspace<br/>[ForecastPage.tsx]"]
end

node_customer(("Customer"))
node_jev["JEV service"]

node_customer -->|"browses and buys"| node_storefront
node_storefront -->|"customizes garments"| node_editor
node_storefront -.->|"requests shop data"| node_browser_api
node_browser_api -.->|"calls API"| node_api
node_api -->|"mounts routes"| node_cart_api
node_cart_api -->|"calls cart methods"| node_odoo_client
node_odoo_client -->|"invokes Odoo API"| node_shop_models
node_design_pricing -.->|"prices order design"| node_shop_models
node_staff_ops -.->|"records commerce operations"| node_shop_models
node_admin_ui -.->|"hosts assistant"| node_chat_ui
node_chat_ui -->|"sends chat requests"| node_chat_routes
node_api -->|"mounts routes"| node_chat_routes
node_admin_ui -.->|"opens analytics"| node_dss_ui
node_dss_ui -.->|"requests forecasts"| node_dss_routes
node_dss_routes -->|"reads DSS data"| node_dss_api
node_dss_api -->|"uses run records"| node_dss_run
node_dss_run -->|"builds run bundle"| node_dss_bundle
node_dss_bundle -->|"canonicalizes data"| node_dss_transform
node_dss_bundle -->|"computes forecast"| node_dss_forecast
node_dss_routes -.->|"obtains AI forecast"| node_ai_forecast
node_ai_forecast -.->|"requests analysis"| node_jev

click node_storefront "https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/pages/Checkout.tsx"
click node_editor "https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/editor/EditorStage.tsx"
click node_browser_api "https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/ziehna/clothcraftv3/blob/main/backend/app/main.py"
click node_cart_api "https://github.com/ziehna/clothcraftv3/blob/main/backend/app/cart_routes.py"
click node_odoo_client "https://github.com/ziehna/clothcraftv3/blob/main/backend/app/odoo.py"
click node_shop_models "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft/models/sale_order.py"
click node_design_pricing "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft/design_fee.py"
click node_staff_ops "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft/models/stock_move.py"
click node_admin_ui "https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/admin/AdminApp.tsx"
click node_chat_ui "https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/admin/assistant/useAssistant.ts"
click node_chat_routes "https://github.com/ziehna/clothcraftv3/blob/main/backend/app/chat_routes.py"
click node_dss_ui "https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/admin/dss/ForecastPage.tsx"
click node_dss_routes "https://github.com/ziehna/clothcraftv3/blob/main/backend/app/jev_forecast_routes.py"
click node_dss_api "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/models/api_dss.py"
click node_dss_run "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/models/dss_run.py"
click node_dss_bundle "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/bundle.py"
click node_dss_transform "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/transform.py"
click node_dss_forecast "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/forecast.py"
click node_ai_forecast "https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss_ai/models/api_dss_ai.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_storefront,node_editor,node_browser_api toneBlue
class node_api,node_cart_api,node_odoo_client,node_chat_routes,node_dss_routes toneAmber
class node_shop_models,node_design_pricing,node_staff_ops toneMint
class node_dss_api,node_dss_run,node_dss_bundle,node_dss_transform,node_dss_forecast,node_ai_forecast toneRose
class node_admin_ui,node_chat_ui,node_dss_ui,node_customer,node_jev toneIndigo
```

## Components

### Customer storefront

- [Shop and checkout](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/pages/Checkout.tsx): `frontend/src/pages/Checkout.tsx`
- [Design editor](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/editor/EditorStage.tsx): `frontend/src/editor/EditorStage.tsx`
- [API client](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API service

- [API application](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/main.py): `backend/app/main.py`
- [Cart routes](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/cart_routes.py): `backend/app/cart_routes.py`
- [Odoo facade](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/odoo.py): `backend/app/odoo.py`
- [Assistant routes](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/chat_routes.py): `backend/app/chat_routes.py`
- [DSS routes](https://github.com/ziehna/clothcraftv3/blob/main/backend/app/jev_forecast_routes.py): `backend/app/jev_forecast_routes.py`

### Odoo commerce

- [Commerce models](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft/models/sale_order.py): `addons/clothcraft/models/sale_order.py`
- [Design pricing](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft/design_fee.py): `addons/clothcraft/design_fee.py`
- [Staff operations](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft/models/stock_move.py): `addons/clothcraft/models/stock_move.py`

### Decision support

- [DSS Odoo API](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/models/api_dss.py): `addons/clothcraft_dss/models/api_dss.py`
- [DSS run storage](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/models/dss_run.py): `addons/clothcraft_dss/models/dss_run.py`
- [Analysis bundle](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/bundle.py): `addons/clothcraft_dss/engine/bundle.py`
- [Canonical transforms](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/transform.py): `addons/clothcraft_dss/engine/transform.py`
- [Demand forecasting](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss/engine/forecast.py): `addons/clothcraft_dss/engine/forecast.py`
- [AI forecast integration](https://github.com/ziehna/clothcraftv3/blob/main/addons/clothcraft_dss_ai/models/api_dss_ai.py): `addons/clothcraft_dss_ai/models/api_dss_ai.py`

### Administration

- [Admin workspace](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/admin/AdminApp.tsx): `frontend/src/admin/AdminApp.tsx`
- [Admin assistant UI](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/admin/assistant/useAssistant.ts): `frontend/src/admin/assistant/useAssistant.ts`
- [DSS workspace](https://github.com/ziehna/clothcraftv3/blob/main/frontend/src/admin/dss/ForecastPage.tsx): `frontend/src/admin/dss/ForecastPage.tsx`

### Other components

- **Customer**
- **JEV service**

## Connections

- Customer → Shop and checkout: browses and buys (evidence: `README.md`)
- Shop and checkout → Design editor: customizes garments (evidence: `README.md`)
- Shop and checkout → API client: requests shop data (evidence: `frontend/src/api/client.ts`)
- API client → API application: calls API (evidence: `frontend/src/api/client.ts`)
- API application → Cart routes: mounts routes (evidence: `backend/app/main.py`)
- Cart routes → Odoo facade: calls cart methods (evidence: `backend/app/cart_routes.py`)
- Odoo facade → Commerce models: invokes Odoo API (evidence: `backend/app/odoo.py`)
- Design pricing → Commerce models: prices order design (evidence: `README.md`)
- Staff operations → Commerce models: records commerce operations (evidence: `README.md`)
- Admin workspace → Admin assistant UI: hosts assistant
- Admin assistant UI → Assistant routes: sends chat requests (evidence: `frontend/src/admin/assistant/useAssistant.ts`)
- API application → Assistant routes: mounts routes (evidence: `backend/app/main.py`)
- Admin workspace → DSS workspace: opens analytics
- DSS workspace → DSS routes: requests forecasts
- DSS routes → DSS Odoo API: reads DSS data (evidence: `backend/app/jev_forecast_routes.py`)
- DSS Odoo API → DSS run storage: uses run records (evidence: `addons/clothcraft_dss/models/api_dss.py`)
- DSS run storage → Analysis bundle: builds run bundle (evidence: `addons/clothcraft_dss/models/dss_run.py`)
- Analysis bundle → Canonical transforms: canonicalizes data (evidence: `addons/clothcraft_dss/engine/bundle.py`)
- Analysis bundle → Demand forecasting: computes forecast (evidence: `addons/clothcraft_dss/engine/bundle.py`)
- DSS routes → AI forecast integration: obtains AI forecast
- AI forecast integration → JEV service: requests analysis