# meykiio/openstore-dz architecture

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

- Interactive diagram: https://gitdiagram.com/meykiio/openstore-dz
- Repository: https://github.com/meykiio/openstore-dz

## Overview

OpenStore DZ is a self-hosted, Arabic-first e-commerce shop for Algerian merchants. Buyers discover products, choose variants and delivery, then submit cash-on-delivery orders; owners configure the shop, manage orders and products, and moderate reviews. Supabase provides the data and authentication layer, while Guepex and optional AI/Telegram integrations extend operations. The main page’s query and layout wiring and the review-moderation flow are evidenced in excerpts; other product branches are represented from README capabilities, so their internal links are kept conservative.

Main entry points: [`src/lib/supabase/client.ts`](https://github.com/meykiio/openstore-dz/blob/main/src/lib/supabase/client.ts) (Shop database), [`src/routes/index.tsx`](https://github.com/meykiio/openstore-dz/blob/main/src/routes/index.tsx) (Home storefront), [`src/routes/admin.index.tsx`](https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.index.tsx) (Owner dashboard), [`src/routes/checkout.tsx`](https://github.com/meykiio/openstore-dz/blob/main/src/routes/checkout.tsx) (COD checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_buyer["Buyer storefront"]
  node_home["Home storefront<br/>[index.tsx]"]
  node_catalogue["Product discovery<br/>[catalogue.ts]"]
  node_product["Product details<br/>[product.$slug.tsx]"]
  node_reviews["Buyer reviews<br/>[reviews.tsx]"]
  node_checkout["COD checkout<br/>[checkout.tsx]"]
  node_tracking["Order tracking<br/>[track.tsx]"]
  node_storeframe["Store layout<br/>[store-layout.tsx]"]
end

subgraph group_commerce["Shop operations"]
  node_setup["Shop setup<br/>[setup.tsx]"]
  node_admin["Owner dashboard<br/>[admin.index.tsx]"]
  node_products["Product management<br/>[admin.products.tsx]"]
  node_orders["Order management<br/>[admin.slips.tsx]"]
  node_moderation["Review moderation<br/>[admin.reviews.tsx]"]
  node_delivery["Delivery operations<br/>[guepex-server.ts]"]
end

subgraph group_platform["Platform services"]
  node_locale["Language and RTL<br/>[i18n-context.tsx]"]
  node_queries["Query services<br/>[queries.ts]"]
  node_supabase[("Shop database<br/>[client.ts]")]
end

subgraph group_integrations["External integrations"]
  node_mcp["AI shop tools<br/>[server.ts]"]
  node_telegram["Order notifications<br/>[telegram.ts]"]
  node_guepex["Guepex carrier"]
end

node_buyer(("Buyer"))
node_owner(("Shop owner"))
node_claude(("Claude assistant"))

node_buyer -->|"opens shop"| node_home
node_home -->|"renders within"| node_storeframe
node_home -->|"loads products"| node_catalogue
node_home -->|"prefetches reviews"| node_queries
node_catalogue -->|"opens product"| node_product
node_product -->|"starts purchase"| node_checkout
node_product -->|"shows reviews"| node_reviews
node_buyer -->|"places order"| node_checkout
node_checkout -->|"creates order"| node_orders
node_buyer -->|"tracks order"| node_tracking
node_owner -->|"configures shop"| node_setup
node_owner -->|"manages shop"| node_admin
node_admin -->|"manages products"| node_products
node_admin -->|"manages orders"| node_orders
node_admin -->|"moderates reviews"| node_moderation
node_moderation -->|"approves reviews"| node_reviews
node_reviews -->|"inserts review"| node_supabase
node_moderation -->|"updates reviews"| node_supabase
node_queries -->|"reads shop data"| node_supabase
node_catalogue -->|"loads catalogue"| node_supabase
node_checkout -->|"records order"| node_supabase
node_orders -->|"creates parcels"| node_delivery
node_delivery -->|"creates shipment"| node_guepex
node_tracking -.->|"syncs status"| node_guepex
node_storeframe -.->|"renders locale"| node_locale
node_owner -->|"connects assistant"| node_mcp
node_claude -->|"calls shop tools"| node_mcp
node_mcp -->|"accesses shop data"| node_supabase
node_orders -.->|"notifies owner"| node_telegram

click node_home "https://github.com/meykiio/openstore-dz/blob/main/src/routes/index.tsx"
click node_catalogue "https://github.com/meykiio/openstore-dz/blob/main/src/lib/catalogue.ts"
click node_product "https://github.com/meykiio/openstore-dz/blob/main/src/routes/product.%24slug.tsx"
click node_reviews "https://github.com/meykiio/openstore-dz/blob/main/src/components/storefront/reviews.tsx"
click node_checkout "https://github.com/meykiio/openstore-dz/blob/main/src/routes/checkout.tsx"
click node_tracking "https://github.com/meykiio/openstore-dz/blob/main/src/routes/track.tsx"
click node_storeframe "https://github.com/meykiio/openstore-dz/blob/main/src/components/storefront/store-layout.tsx"
click node_setup "https://github.com/meykiio/openstore-dz/blob/main/src/routes/setup.tsx"
click node_admin "https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.index.tsx"
click node_products "https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.products.tsx"
click node_orders "https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.slips.tsx"
click node_moderation "https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.reviews.tsx"
click node_delivery "https://github.com/meykiio/openstore-dz/blob/main/src/lib/server/guepex-server.ts"
click node_locale "https://github.com/meykiio/openstore-dz/blob/main/src/lib/i18n-context.tsx"
click node_queries "https://github.com/meykiio/openstore-dz/blob/main/src/lib/queries.ts"
click node_supabase "https://github.com/meykiio/openstore-dz/blob/main/src/lib/supabase/client.ts"
click node_mcp "https://github.com/meykiio/openstore-dz/blob/main/src/lib/server/mcp/server.ts"
click node_telegram "https://github.com/meykiio/openstore-dz/blob/main/src/lib/server/telegram.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_home,node_catalogue,node_product,node_reviews,node_checkout,node_tracking,node_storeframe toneBlue
class node_setup,node_admin,node_products,node_orders,node_moderation,node_delivery toneAmber
class node_locale,node_queries,node_supabase toneMint
class node_mcp,node_telegram,node_guepex toneRose
class node_buyer,node_owner,node_claude toneIndigo
```

## Components

### Buyer storefront

- [Home storefront](https://github.com/meykiio/openstore-dz/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [Product discovery](https://github.com/meykiio/openstore-dz/blob/main/src/lib/catalogue.ts): `src/lib/catalogue.ts`
- [Product details](https://github.com/meykiio/openstore-dz/blob/main/src/routes/product.%24slug.tsx): `src/routes/product.$slug.tsx`
- [Buyer reviews](https://github.com/meykiio/openstore-dz/blob/main/src/components/storefront/reviews.tsx): `src/components/storefront/reviews.tsx`
- [COD checkout](https://github.com/meykiio/openstore-dz/blob/main/src/routes/checkout.tsx): `src/routes/checkout.tsx`
- [Order tracking](https://github.com/meykiio/openstore-dz/blob/main/src/routes/track.tsx): `src/routes/track.tsx`
- [Store layout](https://github.com/meykiio/openstore-dz/blob/main/src/components/storefront/store-layout.tsx): `src/components/storefront/store-layout.tsx`

### Shop operations

- [Shop setup](https://github.com/meykiio/openstore-dz/blob/main/src/routes/setup.tsx): `src/routes/setup.tsx`
- [Owner dashboard](https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.index.tsx): `src/routes/admin.index.tsx`
- [Product management](https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.products.tsx): `src/routes/admin.products.tsx`
- [Order management](https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.slips.tsx): `src/routes/admin.slips.tsx`
- [Review moderation](https://github.com/meykiio/openstore-dz/blob/main/src/routes/admin.reviews.tsx): `src/routes/admin.reviews.tsx`
- [Delivery operations](https://github.com/meykiio/openstore-dz/blob/main/src/lib/server/guepex-server.ts): `src/lib/server/guepex-server.ts`

### Platform services

- [Language and RTL](https://github.com/meykiio/openstore-dz/blob/main/src/lib/i18n-context.tsx): `src/lib/i18n-context.tsx`
- [Query services](https://github.com/meykiio/openstore-dz/blob/main/src/lib/queries.ts): `src/lib/queries.ts`
- [Shop database](https://github.com/meykiio/openstore-dz/blob/main/src/lib/supabase/client.ts): `src/lib/supabase/client.ts`

### External integrations

- [AI shop tools](https://github.com/meykiio/openstore-dz/blob/main/src/lib/server/mcp/server.ts): `src/lib/server/mcp/server.ts`
- [Order notifications](https://github.com/meykiio/openstore-dz/blob/main/src/lib/server/telegram.ts): `src/lib/server/telegram.ts`
- **Guepex carrier**

### Other components

- **Buyer**
- **Shop owner**
- **Claude assistant**

## Connections

- Buyer → Home storefront: opens shop
- Home storefront → Store layout: renders within (evidence: `src/routes/index.tsx`)
- Home storefront → Product discovery: loads products (evidence: `src/routes/index.tsx`)
- Home storefront → Query services: prefetches reviews (evidence: `src/routes/index.tsx`)
- Product discovery → Product details: opens product
- Product details → COD checkout: starts purchase
- Product details → Buyer reviews: shows reviews
- Buyer → COD checkout: places order
- COD checkout → Order management: creates order
- Buyer → Order tracking: tracks order
- Shop owner → Shop setup: configures shop
- Shop owner → Owner dashboard: manages shop
- Owner dashboard → Product management: manages products
- Owner dashboard → Order management: manages orders
- Owner dashboard → Review moderation: moderates reviews
- Review moderation → Buyer reviews: approves reviews (evidence: `src/routes/admin.reviews.tsx`)
- Buyer reviews → Shop database: inserts review (evidence: `src/components/storefront/reviews.tsx`)
- Review moderation → Shop database: updates reviews
- Query services → Shop database: reads shop data (evidence: `src/lib/queries.ts`)
- Product discovery → Shop database: loads catalogue (evidence: `src/lib/catalogue.ts`)
- COD checkout → Shop database: records order
- Order management → Delivery operations: creates parcels
- Delivery operations → Guepex carrier: creates shipment
- Order tracking → Guepex carrier: syncs status
- Store layout → Language and RTL: renders locale
- Shop owner → AI shop tools: connects assistant
- Claude assistant → AI shop tools: calls shop tools
- AI shop tools → Shop database: accesses shop data (evidence: `src/lib/server/mcp/server.ts`)
- Order management → Order notifications: notifies owner
