How xiscorossello/kopeo works
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.