# handyot/motoservice architecture

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

- Interactive diagram: https://gitdiagram.com/handyot/motoservice
- Repository: https://github.com/handyot/motoservice

## Overview

MotoService is a motorcycle and electric-mobility commerce application with a separate admin panel. The main customer transaction path is order verification, Culqi payment, then payment, fiscal-document, and stock updates; catalog browsing and account features are distinct supporting stages. Admin catalog import and management form a separate operational branch. The README is only the generic Next.js starter text, so product capabilities are inferred from the tree and source index; unsampled page and route wiring is left unasserted.

Main entry points: [`app/api/payments/charge/route.ts`](https://github.com/handyot/motoservice/blob/main/app/api/payments/charge/route.ts) (Charge API), [`lib/supabase/server.ts`](https://github.com/handyot/motoservice/blob/main/lib/supabase/server.ts) (Supabase), [`admin-panel/app/api/admin/catalog/manage/route.ts`](https://github.com/handyot/motoservice/blob/main/admin-panel/app/api/admin/catalog/manage/route.ts) (Catalog Admin API), [`admin-panel/app/api/admin/catalog/import/route.ts`](https://github.com/handyot/motoservice/blob/main/admin-panel/app/api/admin/catalog/import/route.ts) (Import API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_catalog_ui["Catalog Pages<br/>[page.tsx]"]
  node_moto_ui["Moto Pages<br/>[page.tsx]"]
  node_catalog_data["Moto Catalog Data<br/>[ecomoto-data.ts]"]
  node_catalog_service["Moto Catalog Service<br/>[ecomoto.service.ts]"]
  node_cart["Cart State<br/>[cart-context.tsx]"]
end

subgraph group_transactions["Commerce Operations"]
  node_checkout["Checkout<br/>[page.tsx]"]
  node_charge_route["Charge API<br/>[route.ts]"]
  node_order_service["Order Service<br/>[order-service.ts]"]
  node_payment_service["Culqi Payments<br/>[culqi.ts]"]
  node_fiscal_service["Fiscal Documents<br/>[fiscal-service.ts]"]
  node_supabase[("Supabase<br/>[server.ts]")]
end

subgraph group_identity["Identity and Accounts"]
  node_auth_pages["Auth Pages<br/>[page.tsx]"]
  node_auth_service["Server Auth<br/>[server.ts]"]
  node_vehicle_service["Vehicle Accounts<br/>[vehicle-service.ts]"]
end

subgraph group_voltia["VoltIA Assistance"]
  node_voltia_api["VoltIA API<br/>[route.ts]"]
  node_voltia_engine["Diagnosis Engine<br/>[voltia-engine.ts]"]
  node_voltia_core["Diagnosis Core<br/>[voltia-core.mjs]"]
end

subgraph group_admin["Administration"]
  node_admin_catalog_api["Catalog Admin API<br/>[route.ts]"]
  node_admin_import_api["Import API<br/>[route.ts]"]
  node_admin_auth["Admin Auth<br/>[server.ts]"]
  node_import_service["Catalog Importer<br/>[import-service.ts]"]
  node_reclassify["Catalog Reclassification"]
  node_status_rules["Product Status Rules"]
end

node_shopper(("Shopper"))
node_culqi{{"Culqi"}}

node_catalog_service -->|"reads data"| node_catalog_data
node_checkout -.->|"submits charge"| node_charge_route
node_charge_route -->|"verifies order"| node_order_service
node_charge_route -->|"processes charge"| node_payment_service
node_charge_route -->|"records payment"| node_supabase
node_charge_route -->|"emits document"| node_fiscal_service
node_charge_route -->|"deducts stock"| node_order_service
node_payment_service -.->|"charges via"| node_culqi
node_auth_service -->|"reads identity"| node_supabase
node_auth_pages -.->|"authenticates"| node_auth_service
node_vehicle_service -->|"persists vehicles"| node_supabase
node_voltia_api -->|"uses client"| node_supabase
node_voltia_engine -->|"delegates to"| node_voltia_core
node_admin_catalog_api -->|"checks access"| node_admin_auth
node_admin_catalog_api -->|"reclassifies"| node_reclassify
node_admin_catalog_api -->|"validates status"| node_status_rules
node_admin_import_api -->|"checks access"| node_admin_auth
node_admin_import_api -->|"runs import"| node_import_service
node_import_service -->|"writes catalog"| node_supabase
node_shopper -.->|"browses"| node_catalog_ui
node_shopper -.->|"checks out"| node_checkout
node_shopper -.->|"signs in"| node_auth_pages

click node_catalog_ui "https://github.com/handyot/motoservice/blob/main/app/repuestos/page.tsx"
click node_moto_ui "https://github.com/handyot/motoservice/blob/main/app/motos/page.tsx"
click node_catalog_data "https://github.com/handyot/motoservice/blob/main/data/ecomoto-data.ts"
click node_catalog_service "https://github.com/handyot/motoservice/blob/main/services/ecomoto.service.ts"
click node_cart "https://github.com/handyot/motoservice/blob/main/lib/cart/cart-context.tsx"
click node_checkout "https://github.com/handyot/motoservice/blob/main/app/checkout/page.tsx"
click node_charge_route "https://github.com/handyot/motoservice/blob/main/app/api/payments/charge/route.ts"
click node_order_service "https://github.com/handyot/motoservice/blob/main/lib/orders/order-service.ts"
click node_payment_service "https://github.com/handyot/motoservice/blob/main/lib/payments/culqi.ts"
click node_fiscal_service "https://github.com/handyot/motoservice/blob/main/lib/documents/fiscal-service.ts"
click node_supabase "https://github.com/handyot/motoservice/blob/main/lib/supabase/server.ts"
click node_auth_pages "https://github.com/handyot/motoservice/blob/main/app/login/page.tsx"
click node_auth_service "https://github.com/handyot/motoservice/blob/main/lib/auth/server.ts"
click node_vehicle_service "https://github.com/handyot/motoservice/blob/main/lib/vehicles/vehicle-service.ts"
click node_voltia_api "https://github.com/handyot/motoservice/blob/main/app/api/voltia/asistencia/route.ts"
click node_voltia_engine "https://github.com/handyot/motoservice/blob/main/lib/voltia/voltia-engine.ts"
click node_voltia_core "https://github.com/handyot/motoservice/blob/main/lib/voltia/voltia-core.mjs"
click node_admin_catalog_api "https://github.com/handyot/motoservice/blob/main/admin-panel/app/api/admin/catalog/manage/route.ts"
click node_admin_import_api "https://github.com/handyot/motoservice/blob/main/admin-panel/app/api/admin/catalog/import/route.ts"
click node_admin_auth "https://github.com/handyot/motoservice/blob/main/admin-panel/lib/auth/server.ts"
click node_import_service "https://github.com/handyot/motoservice/blob/main/lib/importers/import-service.ts"
click node_reclassify "https://github.com/handyot/motoservice/blob/main/lib/catalog/reclassify-service.ts"
click node_status_rules "https://github.com/handyot/motoservice/blob/main/lib/catalog/product-status-core.mjs"

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_catalog_ui,node_moto_ui,node_catalog_data,node_catalog_service,node_cart toneBlue
class node_checkout,node_charge_route,node_order_service,node_payment_service,node_fiscal_service,node_supabase toneAmber
class node_auth_pages,node_auth_service,node_vehicle_service toneMint
class node_voltia_api,node_voltia_engine,node_voltia_core toneRose
class node_admin_catalog_api,node_admin_import_api,node_admin_auth,node_import_service,node_reclassify,node_status_rules,node_shopper,node_culqi toneIndigo
```

## Components

### Storefront

- [Catalog Pages](https://github.com/handyot/motoservice/blob/main/app/repuestos/page.tsx): `app/repuestos/page.tsx`
- [Moto Pages](https://github.com/handyot/motoservice/blob/main/app/motos/page.tsx): `app/motos/page.tsx`
- [Moto Catalog Data](https://github.com/handyot/motoservice/blob/main/data/ecomoto-data.ts): `data/ecomoto-data.ts`
- [Moto Catalog Service](https://github.com/handyot/motoservice/blob/main/services/ecomoto.service.ts): `services/ecomoto.service.ts`
- [Cart State](https://github.com/handyot/motoservice/blob/main/lib/cart/cart-context.tsx): `lib/cart/cart-context.tsx`

### Commerce Operations

- [Checkout](https://github.com/handyot/motoservice/blob/main/app/checkout/page.tsx): `app/checkout/page.tsx`
- [Charge API](https://github.com/handyot/motoservice/blob/main/app/api/payments/charge/route.ts): `app/api/payments/charge/route.ts`
- [Order Service](https://github.com/handyot/motoservice/blob/main/lib/orders/order-service.ts): `lib/orders/order-service.ts`
- [Culqi Payments](https://github.com/handyot/motoservice/blob/main/lib/payments/culqi.ts): `lib/payments/culqi.ts`
- [Fiscal Documents](https://github.com/handyot/motoservice/blob/main/lib/documents/fiscal-service.ts): `lib/documents/fiscal-service.ts`
- [Supabase](https://github.com/handyot/motoservice/blob/main/lib/supabase/server.ts): `lib/supabase/server.ts`

### Identity and Accounts

- [Auth Pages](https://github.com/handyot/motoservice/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Server Auth](https://github.com/handyot/motoservice/blob/main/lib/auth/server.ts): `lib/auth/server.ts`
- [Vehicle Accounts](https://github.com/handyot/motoservice/blob/main/lib/vehicles/vehicle-service.ts): `lib/vehicles/vehicle-service.ts`

### VoltIA Assistance

- [VoltIA API](https://github.com/handyot/motoservice/blob/main/app/api/voltia/asistencia/route.ts): `app/api/voltia/asistencia/route.ts`
- [Diagnosis Engine](https://github.com/handyot/motoservice/blob/main/lib/voltia/voltia-engine.ts): `lib/voltia/voltia-engine.ts`
- [Diagnosis Core](https://github.com/handyot/motoservice/blob/main/lib/voltia/voltia-core.mjs): `lib/voltia/voltia-core.mjs`

### Administration

- [Catalog Admin API](https://github.com/handyot/motoservice/blob/main/admin-panel/app/api/admin/catalog/manage/route.ts): `admin-panel/app/api/admin/catalog/manage/route.ts`
- [Import API](https://github.com/handyot/motoservice/blob/main/admin-panel/app/api/admin/catalog/import/route.ts): `admin-panel/app/api/admin/catalog/import/route.ts`
- [Admin Auth](https://github.com/handyot/motoservice/blob/main/admin-panel/lib/auth/server.ts): `admin-panel/lib/auth/server.ts`
- [Catalog Importer](https://github.com/handyot/motoservice/blob/main/lib/importers/import-service.ts): `lib/importers/import-service.ts`
- [Catalog Reclassification](https://github.com/handyot/motoservice/blob/main/lib/catalog/reclassify-service.ts): `lib/catalog/reclassify-service.ts`
- [Product Status Rules](https://github.com/handyot/motoservice/blob/main/lib/catalog/product-status-core.mjs): `lib/catalog/product-status-core.mjs`

### Other components

- **Shopper**
- **Culqi**

## Connections

- Moto Catalog Service → Moto Catalog Data: reads data (evidence: `services/ecomoto.service.ts`)
- Checkout → Charge API: submits charge
- Charge API → Order Service: verifies order (evidence: `app/api/payments/charge/route.ts`)
- Charge API → Culqi Payments: processes charge (evidence: `app/api/payments/charge/route.ts`)
- Charge API → Supabase: records payment (evidence: `app/api/payments/charge/route.ts`)
- Charge API → Fiscal Documents: emits document (evidence: `app/api/payments/charge/route.ts`)
- Charge API → Order Service: deducts stock (evidence: `app/api/payments/charge/route.ts`)
- Culqi Payments → Culqi: charges via
- Server Auth → Supabase: reads identity (evidence: `lib/auth/server.ts`)
- Auth Pages → Server Auth: authenticates
- Vehicle Accounts → Supabase: persists vehicles (evidence: `lib/vehicles/vehicle-service.ts`)
- VoltIA API → Supabase: uses client (evidence: `app/api/voltia/asistencia/route.ts`)
- Diagnosis Engine → Diagnosis Core: delegates to (evidence: `lib/voltia/voltia-engine.ts`)
- Catalog Admin API → Admin Auth: checks access (evidence: `admin-panel/app/api/admin/catalog/manage/route.ts`)
- Catalog Admin API → Catalog Reclassification: reclassifies (evidence: `admin-panel/app/api/admin/catalog/manage/route.ts`)
- Catalog Admin API → Product Status Rules: validates status (evidence: `admin-panel/app/api/admin/catalog/manage/route.ts`)
- Import API → Admin Auth: checks access (evidence: `admin-panel/app/api/admin/catalog/import/route.ts`)
- Import API → Catalog Importer: runs import (evidence: `admin-panel/app/api/admin/catalog/import/route.ts`)
- Catalog Importer → Supabase: writes catalog (evidence: `lib/importers/import-service.ts`)
- Shopper → Catalog Pages: browses
- Shopper → Checkout: checks out
- Shopper → Auth Pages: signs in