# xiscorossello/kopeo architecture

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

- Interactive diagram: https://gitdiagram.com/xiscorossello/kopeo
- Repository: https://github.com/xiscorossello/kopeo

## Overview

##### Project Type and Purpose
- Kopeo is a full-stack web application built with Next.js (React + TypeScript) that streamlines beverage ticket management for nightlife events.
- It provides:
- A public frontend for event discovery, ticket purchase, and digital wallets.
- A business backoffice (commerce) for product/event CRUD and QR scanning.
- An admin dashboard for global user/commerce/event/product/order management.
- The backend leverages Supabase (PostgreSQL + Auth + RLS) and Stripe (for payments, optional simulation mode).

##### High-Level Components
a. Frontend (Next.js on Vercel)
- Pages under src/app/ (app router)
– Public pages: home, events, event details, auth (login/register/callback), checkout (cancel/success), wallet, scanner.
– Commerce backoffice: /backoffice.
– Admin panel: /admin.
- UI components in src/components.
- Zustand store for shopping cart state (src/store/cart.ts).
- Tailwind CSS for styling.
- QR code generation (qrcode) & scanning (html5-qrcode).
b. Serverless API Routes (Next.js App Router)
- /api/checkout – creates Stripe checkout session.
- /api/webhook – receives Stripe webhook to confirm payment and write orders.
- /auth/callback – handles OAuth callbacks (if any).
c. Backend-as-a-Service (Supabase Cloud)
- Auth: user registration, login, roles (client/commerce/admin).
- Database: PostgreSQL storing users, commerces, events, products, orders with RLS policies.
- Edge functions (optional) or direct DB access via supabase client.
d. External Payments (Stripe)
- Payment gateway: session creation, webhook for payment events.
- Mode simulation when STRIPE_SECRET_KEY missing.
e. Hosting and CI/CD
- Vercel hosts the Next.js app.
- GitHub for version control.
- Supabase Cloud for database and Auth.

##### Relationships and Data Flows
a. User Flow (client)
1. Browser → Next.js page (SSR/SSG or client-side).
2. Stateless UI dispatches actions to Zustand store.
3. On checkout: Next.js /api/checkout → Stripe → user completes payment.
4. Stripe calls /api/webhook → Next.js backend writes order to Supabase.
5. User’s wallet reads orders from Supabase via supabase client.
b. Commerce Flow
1. Commerce user logs in via Supabase Auth.
2. Access /backoffice pages → CRUD on products/events → API calls directly to Supabase.
3. On scanner page: html5-qrcode reads QR → validates ticket by querying Supabase → updates order state.
c. Admin Flow
1. Admin logs in → accesses /admin pages → uses Supabase queries to manage all entities.
d. Supabase Row-Level Security ensures each role only sees allowed rows.
e. CI/CD
– Git push → Vercel deploy → new version live.

##### Architectural Patterns and Principles
- Three-tier structure: Presentation (Next.js UI), Application Logic (Next.js API routes & client code), Data tier (Supabase).
- Serverless Functions pattern for payment logic.
- State management with Zustand for client cart persistence.
- RLS in Supabase ensures security.
- Modular code organization: “app”, “components”, “lib”, “store”, “supabase” migrations.

##### Elements
- Next.js App on Vercel (with sub-sections: Pages, API Routes, Middlewares).
- Supabase Cloud (Auth + PostgreSQL + RLS).
- Stripe Payment Gateway & Webhook flow.
- Client Browsers (Mobile/Web).
- QR Code Generation & Scanner library as utilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    User["Client Browser"]:::ui

    %% Next.js App
    subgraph "Next.js App (Vercel)"
      direction TB
      subgraph "Pages"
        direction TB
        HomePage["Home Page"]:::ui
        EventList["Events Listing"]:::ui
        EventDetails["Event Details"]:::ui
        WalletPage["Wallet"]:::ui
        ScannerPage["Scanner"]:::ui
        LoginPage["Login"]:::ui
        RegisterPage["Register"]:::ui
        OAuthCallbackPage["OAuth Callback"]:::ui
        CheckoutPage["Checkout"]:::ui
        CheckoutSuccess["Checkout Success"]:::ui
        CheckoutCancel["Checkout Cancel"]:::ui
        BOLayout["Backoffice Layout"]:::ui
        BOHome["Commerce Dashboard"]:::ui
        BOProducts["Products Management"]:::ui
        BOEvents["Events Management"]:::ui
        BOCommerce["Commerce Profile"]:::ui
        AdminLayout["Admin Layout"]:::ui
        AdminHome["Admin Dashboard"]:::ui
        AdminUsers["Admin Users"]:::ui
        AdminCommerces["Admin Commerces"]:::ui
        AdminEvents["Admin Events"]:::ui
        AdminProducts["Admin Products"]:::ui
        AdminOrders["Admin Orders"]:::ui
      end
      subgraph "API Routes"
        direction TB
        APICheckout["POST /api/checkout"]:::api
        APIWebhook["POST /api/webhook"]:::api
        APIAuthCallback["/auth/callback"]:::api
      end
      subgraph "UI Components"
        direction TB
        AddressAuto["Address Autocomplete"]:::ui
        CartDrawer["Cart Drawer"]:::ui
        LoadingSpin["Loading Spinner"]:::ui
        LocationMap["Location Map"]:::ui
        Navbar["Navbar"]:::ui
      end
      subgraph "State & Lib"
        direction TB
        CartStore["Zustand Cart Store"]:::api
        SupabaseClient["Supabase Client"]:::api
        SupabaseServer["Supabase Server Util"]:::api
        SupabaseMiddleware["Supabase Middleware"]:::api
        StripeUtil["Stripe Utils"]:::api
      end
    end

    %% Backend and External
    Supabase["Supabase Cloud\nAuth + PostgreSQL + RLS"]:::db
    Stripe["Stripe Gateway"]:::external

    %% Flows
    User --> HomePage
    User --> EventList
    User --> EventDetails
    User --> WalletPage
    User --> ScannerPage
    User --> LoginPage
    User --> RegisterPage
    User --> CheckoutPage

    CheckoutPage --> APICheckout
    APICheckout --> Stripe
    Stripe --> APIWebhook
    APIWebhook --> Supabase

    BOHome --> Supabase
    BOProducts --> Supabase
    BOEvents --> Supabase
    BOCommerce --> Supabase
    ScannerPage --> Supabase

    AdminHome --> Supabase
    AdminUsers --> Supabase
    AdminCommerces --> Supabase
    AdminEvents --> Supabase
    AdminProducts --> Supabase
    AdminOrders --> Supabase

    HomePage --> CartStore
    CheckoutPage --> CartStore
    CartDrawer --> CartStore

    %% Library Flows
    HomePage --> SupabaseClient
    EventList --> SupabaseClient
    EventDetails --> SupabaseClient
    WalletPage --> SupabaseClient
    BOHome --> SupabaseClient
    AdminHome --> SupabaseClient

    APICheckout --> StripeUtil
    APIWebhook --> StripeUtil

    SupabaseClient --> Supabase
    SupabaseServer --> Supabase
    SupabaseMiddleware --> Supabase
    StripeUtil --> Stripe

    %% Click Events
    click HomePage "https://github.com/xiscorossello/kopeo/blob/main/src/app/page.tsx"
    click EventList "https://github.com/xiscorossello/kopeo/blob/main/src/app/event/[id]/page.tsx"
    click EventDetails "https://github.com/xiscorossello/kopeo/blob/main/src/app/event/[id]/page.tsx"
    click WalletPage "https://github.com/xiscorossello/kopeo/blob/main/src/app/wallet/page.tsx"
    click ScannerPage "https://github.com/xiscorossello/kopeo/blob/main/src/app/scanner/page.tsx"
    click LoginPage "https://github.com/xiscorossello/kopeo/blob/main/src/app/auth/login/page.tsx"
    click RegisterPage "https://github.com/xiscorossello/kopeo/blob/main/src/app/auth/register/page.tsx"
    click OAuthCallbackPage "https://github.com/xiscorossello/kopeo/blob/main/src/app/auth/callback/route.ts"
    click CheckoutPage "https://github.com/xiscorossello/kopeo/blob/main/src/app/checkout/page.tsx"
    click CheckoutSuccess "https://github.com/xiscorossello/kopeo/blob/main/src/app/checkout/success/page.tsx"
    click CheckoutCancel "https://github.com/xiscorossello/kopeo/blob/main/src/app/checkout/cancel/page.tsx"
    click BOLayout "https://github.com/xiscorossello/kopeo/blob/main/src/app/backoffice/layout.tsx"
    click BOHome "https://github.com/xiscorossello/kopeo/blob/main/src/app/backoffice/page.tsx"
    click BOProducts "https://github.com/xiscorossello/kopeo/blob/main/src/app/backoffice/products/page.tsx"
    click BOEvents "https://github.com/xiscorossello/kopeo/blob/main/src/app/backoffice/events/page.tsx"
    click BOCommerce "https://github.com/xiscorossello/kopeo/blob/main/src/app/backoffice/commerce/page.tsx"
    click AdminLayout "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/layout.tsx"
    click AdminHome "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/page.tsx"
    click AdminUsers "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/users/page.tsx"
    click AdminCommerces "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/commerces/page.tsx"
    click AdminEvents "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/events/page.tsx"
    click AdminProducts "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/products/page.tsx"
    click AdminOrders "https://github.com/xiscorossello/kopeo/blob/main/src/app/admin/orders/page.tsx"
    click APICheckout "https://github.com/xiscorossello/kopeo/blob/main/src/app/api/checkout/route.ts"
    click APIWebhook "https://github.com/xiscorossello/kopeo/blob/main/src/app/api/webhook/route.ts"
    click APIAuthCallback "https://github.com/xiscorossello/kopeo/blob/main/src/app/auth/callback/route.ts"
    click AddressAuto "https://github.com/xiscorossello/kopeo/blob/main/src/components/AddressAutocomplete.tsx"
    click CartDrawer "https://github.com/xiscorossello/kopeo/blob/main/src/components/CartDrawer.tsx"
    click LoadingSpin "https://github.com/xiscorossello/kopeo/blob/main/src/components/LoadingSpinner.tsx"
    click LocationMap "https://github.com/xiscorossello/kopeo/blob/main/src/components/LocationMap.tsx"
    click Navbar "https://github.com/xiscorossello/kopeo/blob/main/src/components/Navbar.tsx"
    click CartStore "https://github.com/xiscorossello/kopeo/blob/main/src/store/cart.ts"
    click SupabaseClient "https://github.com/xiscorossello/kopeo/blob/main/src/lib/supabase/client.ts"
    click SupabaseServer "https://github.com/xiscorossello/kopeo/blob/main/src/lib/supabase/server.ts"
    click SupabaseMiddleware "https://github.com/xiscorossello/kopeo/blob/main/src/lib/supabase/middleware.ts"
    click StripeUtil "https://github.com/xiscorossello/kopeo/blob/main/src/lib/stripe.ts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef api fill:#D0F0D0,stroke:#000,stroke-width:1px
    classDef db fill:#FFD0D0,stroke:#000,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#000,stroke-width:1px
```
