# zephyrstudio-tech/v0-pos-arte21 architecture

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

- Interactive diagram: https://gitdiagram.com/zephyrstudio-tech/v0-pos-arte21
- Repository: https://github.com/zephyrstudio-tech/v0-pos-arte21

## Overview

Arte21 POS is a retail point-of-sale and omnichannel operations system. Store operators use the POS to manage products, customers, cash sessions, sales and returns; administrators manage catalog, online orders, customers and reporting. The documented architecture connects the web application to Supabase and WooCommerce, and sends invoices to VeriFACTU. The source excerpts also show server-side sale and catalog logic. Some feature areas are represented by their exact tree paths, but their internal calls were not sampled, so uncertain links are omitted.

Main entry points: [`app/layout.tsx`](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/layout.tsx) (Arte21 web app), [`app/api/admin/web-orders/route.ts`](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/web-orders/route.ts) (Online order handling), [`app/(pos)/pos/page.tsx`](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(pos)/pos/page.tsx) (POS workspace), [`app/api/sales/create/route.ts`](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/sales/create/route.ts) (Sale processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pos["Store POS"]
  node_pos_ui["POS workspace<br/>[page.tsx]"]
  node_pos_state["POS ticket state<br/>[usePosStore.ts]"]
  node_sale_api["Sale processing<br/>[route.ts]"]
end

subgraph group_commerce["Commerce Operations"]
  node_web_orders_ui["Online order desk<br/>[page.tsx]"]
  node_web_orders_api["Online order handling<br/>[route.ts]"]
  node_shipping["Order shipping"]
  node_invoices["Invoice services<br/>[invoices.ts]"]
  node_club["Customer club"]
end

subgraph group_admin["Administration"]
  node_catalog_ui["Catalog management<br/>[page.tsx]"]
  node_catalog_api["Catalog API<br/>[route.ts]"]
  node_stock_ui["Stock management<br/>[page.tsx]"]
  node_dashboard_api["Dashboard metrics<br/>[route.ts]"]
  node_customer_api["Customer records<br/>[route.ts]"]
end

subgraph group_platform["Platform Services"]
  node_app["Arte21 web app<br/>[layout.tsx]"]
  node_office["Office assistant<br/>[ejecutar.ts]"]
  node_sync["Background sync<br/>[sync-queue.ts]"]
  node_database[("Supabase database")]
end

node_operator(("Store operator"))
node_admin_user(("Administrator"))
node_woocommerce["WooCommerce"]
node_verifactu["AEAT VeriFACTU"]

node_operator -->|"uses"| node_app
node_admin_user -->|"manages"| node_app
node_app -->|"reads and writes"| node_database
node_app -->|"syncs stock and prices"| node_woocommerce
node_woocommerce -->|"sends webhooks"| node_app
node_app -->|"registers invoices"| node_verifactu
node_pos_ui -.->|"uses ticket state"| node_pos_state
node_pos_ui -.->|"submits sales"| node_sale_api
node_sale_api -->|"creates sales"| node_database
node_catalog_ui -.->|"manages products"| node_catalog_api
node_catalog_api -->|"reads and writes"| node_database
node_stock_ui -.->|"manages stock"| node_database
node_dashboard_api -->|"queries metrics"| node_database
node_customer_api -->|"reads customer data"| node_database
node_web_orders_ui -.->|"manages orders"| node_web_orders_api
node_web_orders_api -->|"reads orders"| node_database
node_web_orders_api -->|"uses shipping display"| node_shipping
node_sync -.->|"syncs asynchronously"| node_woocommerce
node_invoices -.->|"registers fiscal documents"| node_verifactu

click node_app "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/layout.tsx"
click node_pos_ui "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(pos)/pos/page.tsx"
click node_pos_state "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/store/usePosStore.ts"
click node_sale_api "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/sales/create/route.ts"
click node_catalog_ui "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(admin)/admin/products/page.tsx"
click node_catalog_api "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/products/route.ts"
click node_stock_ui "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(admin)/admin/stock/page.tsx"
click node_dashboard_api "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/dashboard/route.ts"
click node_customer_api "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/customers/route.ts"
click node_web_orders_ui "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(admin)/admin/pedidos-web/page.tsx"
click node_web_orders_api "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/web-orders/route.ts"
click node_shipping "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/web-order-shipping.ts"
click node_invoices "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/invoices.ts"
click node_club "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/club-credencial-servidor.ts"
click node_office "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/oficina/ejecutar.ts"
click node_sync "https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/sync-queue.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_pos_ui,node_pos_state,node_sale_api toneBlue
class node_web_orders_ui,node_web_orders_api,node_shipping,node_invoices,node_club toneAmber
class node_catalog_ui,node_catalog_api,node_stock_ui,node_dashboard_api,node_customer_api toneMint
class node_app,node_office,node_sync,node_database toneRose
class node_operator,node_admin_user,node_woocommerce,node_verifactu toneIndigo
```

## Components

### Store POS

- [POS workspace](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(pos)/pos/page.tsx): `app/(pos)/pos/page.tsx`
- [POS ticket state](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/store/usePosStore.ts): `lib/store/usePosStore.ts`
- [Sale processing](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/sales/create/route.ts): `app/api/sales/create/route.ts`

### Commerce Operations

- [Online order desk](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(admin)/admin/pedidos-web/page.tsx): `app/(admin)/admin/pedidos-web/page.tsx`
- [Online order handling](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/web-orders/route.ts): `app/api/admin/web-orders/route.ts`
- [Order shipping](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/web-order-shipping.ts): `lib/web-order-shipping.ts`
- [Invoice services](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/invoices.ts): `lib/invoices.ts`
- [Customer club](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/club-credencial-servidor.ts): `lib/club-credencial-servidor.ts`

### Administration

- [Catalog management](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(admin)/admin/products/page.tsx): `app/(admin)/admin/products/page.tsx`
- [Catalog API](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/products/route.ts): `app/api/admin/products/route.ts`
- [Stock management](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/(admin)/admin/stock/page.tsx): `app/(admin)/admin/stock/page.tsx`
- [Dashboard metrics](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/dashboard/route.ts): `app/api/admin/dashboard/route.ts`
- [Customer records](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/api/admin/customers/route.ts): `app/api/admin/customers/route.ts`

### Platform Services

- [Arte21 web app](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/app/layout.tsx): `app/layout.tsx`
- [Office assistant](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/oficina/ejecutar.ts): `lib/oficina/ejecutar.ts`
- [Background sync](https://github.com/zephyrstudio-tech/v0-pos-arte21/blob/main/lib/sync-queue.ts): `lib/sync-queue.ts`
- **Supabase database**

### Other components

- **Store operator**
- **Administrator**
- **WooCommerce**
- **AEAT VeriFACTU**

## Connections

- Store operator → Arte21 web app: uses
- Administrator → Arte21 web app: manages
- Arte21 web app → Supabase database: reads and writes
- Arte21 web app → WooCommerce: syncs stock and prices
- WooCommerce → Arte21 web app: sends webhooks
- Arte21 web app → AEAT VeriFACTU: registers invoices
- POS workspace → POS ticket state: uses ticket state (evidence: `app/(pos)/pos/page.tsx`)
- POS workspace → Sale processing: submits sales
- Sale processing → Supabase database: creates sales (evidence: `app/api/sales/create/route.ts`)
- Catalog management → Catalog API: manages products
- Catalog API → Supabase database: reads and writes (evidence: `app/api/admin/products/route.ts`)
- Stock management → Supabase database: manages stock
- Dashboard metrics → Supabase database: queries metrics (evidence: `app/api/admin/dashboard/route.ts`)
- Customer records → Supabase database: reads customer data (evidence: `app/api/admin/customers/route.ts`)
- Online order desk → Online order handling: manages orders
- Online order handling → Supabase database: reads orders (evidence: `app/api/admin/web-orders/route.ts`)
- Online order handling → Order shipping: uses shipping display (evidence: `app/api/admin/web-orders/route.ts`)
- Background sync → WooCommerce: syncs asynchronously
- Invoice services → AEAT VeriFACTU: registers fiscal documents