# variablevic/zion architecture

> Architecture diagram of the GitHub repository variablevic/zion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/variablevic/zion
- Repository: https://github.com/variablevic/zion

## Overview

##### Project type and purpose
- This is a full-stack e-commerce storefront called “Zion” that layers AI-powered interactions onto a traditional shopping flow.
- The frontend is a Next.js App-Router application (“storefront” folder), and the backend is a Medusa commerce server (“medusa” folder).
- It uses AI (OpenAI via Vercel AI SDK), vector search (Upstash Vector), Redis state (Upstash Redis), and Supabase for storage.

##### File structure
- Top-level folders:
- medusa – the commerce engine, with core API routes, custom extensions, jobs, subscribers, modules, scripts, workflows, and integration tests.
- storefront – Next.js App Router layout, pages, serverless API routes, React components, hooks, context, and utility libraries.
- Key patterns:
- Medusa’s “src/api” and “src/modules” implement custom endpoints (generate-products, upsert-to-vector).
- Subscribers (event listeners) push data into the vector store or cleanup.
- Scripts and workflows in Medusa seed data and orchestrate vector upserts.
- Next.js “app/api/*” implements serverless routes for AI chat, canvas streaming, and product retrieval.
- The storefront uses a worker-based agent model under “lib/agent” for orchestrating AI tasks.

##### README for additional insights
- Confirms tech stack: Next.js App Router, Medusa, Vercel AI SDK, OpenAI, Upstash (Redis + Vector), Supabase.
- Describes core value: AI assistant drives UI generation, personalized recommendations, story-driven product displays, full cart & checkout via chat.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend (Next.js)" 
        direction TB
        UI["Global Layout & Entry Page"]:::frontend
        ProductPage["Product Page (UI)"]:::frontend
        DrawerPage["Drawer Product Page (UI)"]:::frontend
        ChatRoute["Next.js AI Chat Route"]:::frontend
        CanvasData["Next.js Canvas Data Route"]:::frontend
        CanvasStream["Next.js Canvas Streaming Route"]:::frontend
        AgentCore["AI Agent Core Library"]:::frontend
        AgentWorker["AI Agent Worker Implementations"]:::frontend
        CanvasComp["React UI Components (Canvas)"]:::frontend
        ChatComp["React UI Components (Chat)"]:::frontend
        CartComp["React UI Components (Cart)"]:::frontend
        CartCtx["Cart Context"]:::frontend
    end

    %% Backend Zone
    subgraph "Backend (Medusa Commerce Engine)"
        direction TB
        MedusaAPI["Medusa Commerce Engine Core API"]:::backend
        GenProdEP["Generate Products Endpoint"]:::backend
        UpsertVectorEP["Upsert Products to Vector Endpoint"]:::backend
        AdminCustom["Custom Admin API Extensions"]:::backend
        StoreCustom["Custom Store API Extensions"]:::backend
        FileModule["File Service Module"]:::backend
        VectorModule["Vector Service Module"]:::backend
        SubUpsert["Subscriber for Vector Upsert"]:::backend
        SubDelete["Subscriber for Vector Deletion"]:::backend
        ScriptGen["Generate Products Script"]:::backend
        ScriptSeed["Seed Data Script"]:::backend
        ScriptUpsert["Upsert Products to Vector Script"]:::backend
        WFGen["Generate Products Workflow"]:::backend
        WFUpsert["Upsert Products Workflow"]:::backend
        MedusaConfig["Medusa Configuration"]:::backend
        IntTests["Integration Tests Suite"]:::backend
    end

    %% Datastores
    subgraph "Databases & State Stores"
        direction TB
        PrimaryDB[(Primary DB)]:::datastore
        Redis[(Upstash Redis)]:::datastore
        VectorStore[(Upstash Vector Store)]:::datastore
        Supabase[(Supabase Storage)]:::datastore
    end

    %% External AI
    subgraph "External AI Services"
        direction TB
        OpenAI[(OpenAI API)]:::external
        VercelAI[(Vercel AI SDK)]:::external
    end

    %% Connections
    User["User"]:::external -->|"browsing & chat input"| UI
    UI -->|navigates to| ProductPage
    UI -->|navigates to| DrawerPage
    UI -->|POST /api/chat| ChatRoute
    UI -->|GET /api/canvas/:id| CanvasData
    UI -->|STREAM /api/canvas/:id/stream| CanvasStream
    ChatRoute -->|calls chat| OpenAI
    ChatRoute -->|uses| VercelAI
    CanvasData -->|read/write| Redis
    CanvasStream -->|read/write| Redis
    ChatRoute -->|fetch products/cart| MedusaAPI
    MedusaAPI -->|CRUD| PrimaryDB
    MedusaAPI -->|uploads/downloads| Supabase
    AdminCustom -->|extends| MedusaAPI
    StoreCustom -->|extends| MedusaAPI
    GenProdEP -->|writes| PrimaryDB
    UpsertVectorEP -->|invokes| VectorModule
    FileModule -->|manages files| Supabase
    VectorModule -->|manages vectors| VectorStore
    SubUpsert -->|on product create/update| VectorStore
    SubDelete -->|on product delete| VectorStore
    ScriptGen -->|batch seed| PrimaryDB
    ScriptSeed -->|seed data| PrimaryDB
    ScriptUpsert -->|batch upsert| VectorStore
    WFGen -->|orchestrates| ScriptGen
    WFUpsert -->|orchestrates| ScriptUpsert
    Supabase -->|assets| UI
    Supabase -->|assets| MedusaAPI

    AgentCore -->|orchestrates| AgentWorker
    AgentWorker -->|drives| ChatRoute
    AgentWorker -->|drives| CanvasData

    IntTests -->|tests| MedusaAPI

    %% Click Events
    click UI "https://github.com/variablevic/zion/blob/main/storefront/app/layout.tsx"
    click UI "https://github.com/variablevic/zion/blob/main/storefront/app/page.tsx"
    click ProductPage "https://github.com/variablevic/zion/blob/main/storefront/app/product/[id]/page.tsx"
    click DrawerPage "https://github.com/variablevic/zion/blob/main/storefront/app/@drawer/(.)product/[id]/page.tsx"
    click ChatRoute "https://github.com/variablevic/zion/blob/main/storefront/app/api/chat/route.ts"
    click CanvasData "https://github.com/variablevic/zion/blob/main/storefront/app/api/canvas/[id]/route.ts"
    click CanvasStream "https://github.com/variablevic/zion/blob/main/storefront/app/api/canvas/[id]/stream/route.ts"
    click AgentCore "https://github.com/variablevic/zion/blob/main/storefront/lib/agent/core/agent.ts"
    click AgentCore "https://github.com/variablevic/zion/blob/main/storefront/lib/agent/core/worker.ts"
    click AgentWorker "https://github.com/variablevic/zion/blob/main/storefront/lib/agent/workers/product-worker.ts"
    click MedusaAPI "https://github.com/variablevic/zion/tree/main/medusa/src/api"
    click GenProdEP "https://github.com/variablevic/zion/blob/main/medusa/src/api/generate-products/route.ts"
    click UpsertVectorEP "https://github.com/variablevic/zion/blob/main/medusa/src/api/upsert-products-to-vector/route.ts"
    click AdminCustom "https://github.com/variablevic/zion/blob/main/medusa/src/api/admin/custom/route.ts"
    click StoreCustom "https://github.com/variablevic/zion/blob/main/medusa/src/api/store/custom/route.ts"
    click FileModule "https://github.com/variablevic/zion/blob/main/medusa/src/modules/file/service.ts"
    click VectorModule "https://github.com/variablevic/zion/blob/main/medusa/src/modules/vector/service.ts"
    click SubUpsert "https://github.com/variablevic/zion/blob/main/medusa/src/subscribers/upsert-vector-db.ts"
    click SubDelete "https://github.com/variablevic/zion/blob/main/medusa/src/subscribers/delete-from-vector-db.ts"
    click ScriptGen "https://github.com/variablevic/zion/blob/main/medusa/src/scripts/generate-products.ts"
    click ScriptSeed "https://github.com/variablevic/zion/blob/main/medusa/src/scripts/seed.ts"
    click ScriptUpsert "https://github.com/variablevic/zion/blob/main/medusa/src/scripts/upsert-products-to-vector.ts"
    click WFGen "https://github.com/variablevic/zion/blob/main/medusa/src/workflows/generate-products.ts"
    click WFUpsert "https://github.com/variablevic/zion/blob/main/medusa/src/workflows/upsert-products-to-vector.ts"
    click IntTests "https://github.com/variablevic/zion/tree/main/medusa/integration-tests"
    click CartCtx "https://github.com/variablevic/zion/blob/main/storefront/context/cart-context.tsx"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef datastore fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
