# hectordev2/corrales-web architecture

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

- Interactive diagram: https://gitdiagram.com/hectordev2/corrales-web
- Repository: https://github.com/hectordev2/corrales-web

## Overview

1. **High-level shape**
   - This is a **Next.js 16 App Router** application for a restaurant business, split into three user-facing areas: **public customer site**, **admin panel**, and **delivery panel**.
   - The main runtime is the browser + Next.js server, with most persistent data stored in **Supabase**.

2. **Route architecture**
   - The `src/app` tree is organized by route groups:
     - `/(public)` for the customer-facing site: home, menu, checkout, reservas, nosotros.
     - `/(admin)/admin` for management screens, including product CRUD.
     - `/(delivery)/delivery` for courier order handling.
     - `/login` for authentication.
     - `/api/payment/charge` for payment processing.
   - Each route group has its own layout, which is a clean boundary for shared navigation and page chrome.

3. **Primary backend dependency: Supabase**
   - Supabase provides **PostgreSQL**, **Auth**, **Storage**, and **Realtime**.
   - The app relies on Supabase for:
     - product catalog and variants,
     - orders and order status,
     - reservations,
     - user profiles and roles,
     - product image storage,
     - realtime updates for the admin order view.
   - The repo includes SQL migrations under `supabase/migrations`, so the database schema and policies are part of the application architecture, not an external afterthought.

4. **Authentication and authorization boundary**
   - Access control is role-based: **public**, **admin**, and **delivery**.
   - The README says roles are enforced with **Supabase RLS** using a DB function like `current_user_role()`.
   - `src/middleware.ts` likely adds route protection at the Next.js edge/server boundary, while the database enforces the real security rules.
   - This means the auth model is layered: UI routing + middleware + database policies.

5. **Data access layer**
   - `src/lib/api/*` is the main application data boundary.
   - The modules are separated by domain:
     - `products.ts` for catalog CRUD and image upload,
     - `orders.ts` for order creation,
     - `admin.ts` for admin operations like assignments and order updates,
     - `reservations.ts` for booking records,
     - `delivery.ts` for courier-related queries/actions.
   - This layer isolates Supabase calls from UI components, which is the main backend-facing abstraction in the repo.

6. **Customer ordering flow**
   - The public menu page fetches products and variants, displays them in cards, and lets users add items to a cart.
   - Cart state is held in **Zustand** (`src/store/cart.ts`) rather than in the database, so the cart is a client-side session state boundary.
   - Checkout combines cart contents with customer details and delivery/recojo choice, then sends an order through the application’s order layer.
   - Payment is integrated with **Culqi**, with a dedicated API route for the charge/webhook path.

7. **Admin operations flow**
   - The admin area is centered on operational management of orders and products.
   - Order management is realtime-driven, using Supabase Realtime to update active orders without manual refresh.
   - Admin actions include changing order status, assigning delivery staff, canceling orders, and viewing daily stats.
   - Product management includes create/edit/soft-delete, variant management, and image upload to Supabase Storage.

8. **Delivery workflow**
   - The delivery panel is a separate route group, focused on orders assigned to the authenticated courier.
   - The presence of a “self-assign” migration indicates delivery users can take ownership of orders through database-backed workflow rules.
   - This is a distinct operational view over the same order data, not a separate subsystem or database.

9. **Content and media storage**
   - Product photos live in a public Supabase Storage bucket named `product-images`.
   - The admin product editor supports preview before upload and image replacement, so the storage bucket is part of the catalog management path.
   - Because images are public, the menu UI can render them without auth, while write access remains restricted by storage policies.

10. **Forms and validation**
   - Form-heavy flows use `react-hook-form` plus **Zod** schemas.
   - The important validated forms are checkout and reservation, and likely the admin product form as well.
   - This creates a clear boundary between UI input handling and domain validation.

11. **Shared UI and presentation layers**
   - Reusable components are grouped by domain under `src/components/*`, with shared layout pieces in `components/layout`.
   - The app uses **Tailwind CSS v4** and **Material Symbols**, so most visual structure is component-driven rather than CSS-module driven.
   - Common shell elements like header, bottom navigation, cart button, and mobile menu are shared across public pages.

12. **Database-centric business logic**
   - The migrations show that important workflows are implemented in SQL, including seed data, order creation RPCs, delivery assignment, and storage/RLS setup.
   - That means some critical business rules live in the database layer rather than in Next.js code, which matters for any architecture diagram.
   - The generated `database.types.ts` indicates the frontend is typed directly against the Supabase schema.

13. **Operational concerns**
   - The project includes PWA support via `next-pwa`, so the public experience is designed to be installable/offline-friendly to some extent.
   - `vitest` setup suggests the repo has room for unit tests around the data layer and UI behavior, though the README notes tests are still a future improvement.
   - Tooling like ESLint, Prettier, and TypeScript define a strongly typed frontend codebase with standard Next.js build/runtime behavior.

14. **Core system diagram to keep in mind**
   - The main interaction loop is:
     - browser UI → Next.js pages/components → Supabase data layer,
     - browser UI → cart state in Zustand → checkout/order submission,
     - admin/delivery UI → Supabase Realtime / RLS-protected operations,
     - checkout/payment path → Next.js API route → Culqi.
   - In short: **Next.js is the orchestration layer; Supabase is the system of record; Culqi is the payment provider; Zustand is only local session state**.

Main entry points: [`src/lib/supabase-server.ts`](https://github.com/hectordev2/corrales-web/blob/main/src/lib/supabase-server.ts) (Supabase client), [`src/app/(public)`](https://github.com/hectordev2/corrales-web/tree/main/src/app/(public)) (Public site), [`src/app/layout.tsx`](https://github.com/hectordev2/corrales-web/blob/main/src/app/layout.tsx) (Root layout), [`src/lib/api/orders.ts`](https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/orders.ts) (Orders API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_app_layout["Root layout<br/>Next.js shell<br/>[layout.tsx]"]
  node_public_routes["Public site<br/>route group"]
  node_admin_routes["Admin area<br/>route group"]
  node_delivery_routes["Delivery area<br/>route group"]
  node_login_page["Login<br/>auth page<br/>[page.tsx]"]
  node_payment_api["Charge API<br/>Next.js API<br/>[route.ts]"]
end

subgraph group_ui["Shared UI"]
  node_header_shell["Site chrome<br/>layout components"]
end

subgraph group_domain["Feature flows"]
  node_home_ui["Home view<br/>public page"]
  node_menu_ui["Menu view<br/>catalog page"]
  node_checkout_ui["Checkout flow<br/>order form"]
  node_reservas_ui["Reservations<br/>booking form"]
  node_admin_ui["Admin dashboard<br/>ops view"]
  node_delivery_ui["Delivery view<br/>courier view"]
end

subgraph group_data["Data layer"]
  node_cart_store(("Cart store<br/>Zustand state<br/>[cart.ts]"))
  node_user_store(("User store<br/>client state<br/>[user.ts]"))
  node_api_products["Products API<br/>data access<br/>[products.ts]"]
  node_api_orders["Orders API<br/>data access<br/>[orders.ts]"]
  node_api_admin["Admin API<br/>data access<br/>[admin.ts]"]
  node_api_delivery["Delivery API<br/>data access<br/>[delivery.ts]"]
  node_api_reservations["Reservations API<br/>data access<br/>[reservations.ts]"]
  node_middleware["Route guard<br/>Next.js middleware<br/>[middleware.ts]"]
end

subgraph group_backend["Backend platform"]
  node_supabase_server["Supabase client<br/>server client<br/>[supabase-server.ts]"]
  node_supabase_types["DB types<br/>generated types<br/>[database.types.ts]"]
  node_supabase_migrations[("Migrations<br/>SQL schema")]
  node_supabase_storage[("Product images<br/>storage bucket")]
  node_culqi{{"Culqi<br/>payment provider"}}
end

node_app_layout -->|"wraps"| node_public_routes
node_app_layout -->|"wraps"| node_admin_routes
node_app_layout -->|"wraps"| node_delivery_routes
node_app_layout -->|"renders"| node_login_page
node_public_routes -->|"hosts"| node_home_ui
node_public_routes -->|"hosts"| node_menu_ui
node_public_routes -->|"hosts"| node_checkout_ui
node_public_routes -->|"hosts"| node_reservas_ui
node_admin_routes -->|"hosts"| node_admin_ui
node_delivery_routes -->|"hosts"| node_delivery_ui
node_header_shell -->|"shared with"| node_home_ui
node_header_shell -->|"shared with"| node_menu_ui
node_menu_ui -->|"uses"| node_cart_store
node_checkout_ui -->|"reads"| node_cart_store
node_checkout_ui -->|"submits"| node_api_orders
node_reservas_ui -->|"submits"| node_api_reservations
node_admin_ui -->|"manages"| node_api_admin
node_admin_ui -->|"manages"| node_api_products
node_delivery_ui -->|"queries"| node_api_delivery
node_login_page -->|"updates"| node_user_store
node_middleware -->|"protects"| node_admin_routes
node_middleware -->|"protects"| node_delivery_routes
node_api_products -->|"calls"| node_supabase_server
node_api_orders -->|"calls"| node_supabase_server
node_api_admin -->|"calls"| node_supabase_server
node_api_delivery -->|"calls"| node_supabase_server
node_api_reservations -->|"calls"| node_supabase_server
node_supabase_server -->|"typed by"| node_supabase_types
node_supabase_server -->|"backed by"| node_supabase_migrations
node_supabase_migrations -->|"defines"| node_supabase_storage
node_api_products -->|"uploads"| node_supabase_storage
node_api_orders -->|"charges"| node_culqi
node_payment_api -->|"integrates"| node_culqi
node_payment_api -->|"completes"| node_api_orders

click node_app_layout "https://github.com/hectordev2/corrales-web/blob/main/src/app/layout.tsx"
click node_public_routes "https://github.com/hectordev2/corrales-web/tree/main/src/app/(public)"
click node_admin_routes "https://github.com/hectordev2/corrales-web/tree/main/src/app/(admin)"
click node_delivery_routes "https://github.com/hectordev2/corrales-web/tree/main/src/app/(delivery)"
click node_login_page "https://github.com/hectordev2/corrales-web/blob/main/src/app/login/page.tsx"
click node_payment_api "https://github.com/hectordev2/corrales-web/blob/main/src/app/api/payment/charge/route.ts"
click node_header_shell "https://github.com/hectordev2/corrales-web/tree/main/src/components/layout"
click node_home_ui "https://github.com/hectordev2/corrales-web/tree/main/src/components/home"
click node_menu_ui "https://github.com/hectordev2/corrales-web/tree/main/src/components/menu"
click node_checkout_ui "https://github.com/hectordev2/corrales-web/tree/main/src/components/checkout"
click node_reservas_ui "https://github.com/hectordev2/corrales-web/tree/main/src/components/reservas"
click node_admin_ui "https://github.com/hectordev2/corrales-web/tree/main/src/components/admin"
click node_delivery_ui "https://github.com/hectordev2/corrales-web/tree/main/src/components/delivery"
click node_cart_store "https://github.com/hectordev2/corrales-web/blob/main/src/store/cart.ts"
click node_user_store "https://github.com/hectordev2/corrales-web/blob/main/src/store/user.ts"
click node_api_products "https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/products.ts"
click node_api_orders "https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/orders.ts"
click node_api_admin "https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/admin.ts"
click node_api_delivery "https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/delivery.ts"
click node_api_reservations "https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/reservations.ts"
click node_middleware "https://github.com/hectordev2/corrales-web/blob/main/src/middleware.ts"
click node_supabase_server "https://github.com/hectordev2/corrales-web/blob/main/src/lib/supabase-server.ts"
click node_supabase_types "https://github.com/hectordev2/corrales-web/blob/main/src/types/database.types.ts"
click node_supabase_migrations "https://github.com/hectordev2/corrales-web/tree/main/supabase/migrations"
click node_supabase_storage "https://github.com/hectordev2/corrales-web/blob/main/supabase/migrations/20260409000000_product_images_storage.sql"

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_app_layout,node_public_routes,node_admin_routes,node_delivery_routes,node_login_page,node_payment_api toneBlue
class node_header_shell toneAmber
class node_home_ui,node_menu_ui,node_checkout_ui,node_reservas_ui,node_admin_ui,node_delivery_ui toneMint
class node_cart_store,node_user_store,node_api_products,node_api_orders,node_api_admin,node_api_delivery,node_api_reservations,node_middleware toneRose
class node_supabase_server,node_supabase_types,node_supabase_migrations,node_supabase_storage,node_culqi toneIndigo
```

## Components

### App routes

Next.js App Router entrypoints and route groups

- [Root layout](https://github.com/hectordev2/corrales-web/blob/main/src/app/layout.tsx): Next.js shell · Global app shell and shared metadata/styles · `src/app/layout.tsx`
- [Public site](https://github.com/hectordev2/corrales-web/tree/main/src/app/(public)): route group · Customer-facing pages for home, menu, checkout, reservations, and about · `src/app/(public)`
- [Admin area](https://github.com/hectordev2/corrales-web/tree/main/src/app/(admin)): route group · Management screens under the admin route group · `src/app/(admin)`
- [Delivery area](https://github.com/hectordev2/corrales-web/tree/main/src/app/(delivery)): route group · Courier workflow screens under the delivery route group · `src/app/(delivery)`
- [Login](https://github.com/hectordev2/corrales-web/blob/main/src/app/login/page.tsx): auth page · Authentication entry point · `src/app/login/page.tsx`
- [Charge API](https://github.com/hectordev2/corrales-web/blob/main/src/app/api/payment/charge/route.ts): Next.js API · Server endpoint for payment processing · `src/app/api/payment/charge/route.ts`

### Shared UI

Reusable presentation components and page shells

- [Site chrome](https://github.com/hectordev2/corrales-web/tree/main/src/components/layout): layout components · Shared header, bottom nav, cart button, and mobile menu · `src/components/layout`

### Feature flows

Customer, admin, and delivery experiences

- [Home view](https://github.com/hectordev2/corrales-web/tree/main/src/components/home): public page · Hero and landing content for the public site · `src/components/home`
- [Menu view](https://github.com/hectordev2/corrales-web/tree/main/src/components/menu): catalog page · Product browsing and add-to-cart experience · `src/components/menu`
- [Checkout flow](https://github.com/hectordev2/corrales-web/tree/main/src/components/checkout): order form · Cart review and customer checkout submission · `src/components/checkout`
- [Reservations](https://github.com/hectordev2/corrales-web/tree/main/src/components/reservas): booking form · Reservation entry and validation flow · `src/components/reservas`
- [Admin dashboard](https://github.com/hectordev2/corrales-web/tree/main/src/components/admin): ops view · Order management, stats, and product administration · `src/components/admin`
- [Delivery view](https://github.com/hectordev2/corrales-web/tree/main/src/components/delivery): courier view · Assigned-order workflow for delivery staff · `src/components/delivery`

### Data layer

Client/server Supabase access and local state

- [Cart store](https://github.com/hectordev2/corrales-web/blob/main/src/store/cart.ts): Zustand state · Client-side cart session state · `src/store/cart.ts`
- [User store](https://github.com/hectordev2/corrales-web/blob/main/src/store/user.ts): client state · Local user/session state used by the app · `src/store/user.ts`
- [Products API](https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/products.ts): data access · Catalog CRUD, variants, and image upload operations · `src/lib/api/products.ts`
- [Orders API](https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/orders.ts): data access · Customer order creation and order retrieval · `src/lib/api/orders.ts`
- [Admin API](https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/admin.ts): data access · Order status, assignment, and administrative mutations · `src/lib/api/admin.ts`
- [Delivery API](https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/delivery.ts): data access · Courier-specific order queries and actions · `src/lib/api/delivery.ts`
- [Reservations API](https://github.com/hectordev2/corrales-web/blob/main/src/lib/api/reservations.ts): data access · Reservation persistence and retrieval · `src/lib/api/reservations.ts`
- [Route guard](https://github.com/hectordev2/corrales-web/blob/main/src/middleware.ts): Next.js middleware · Edge/server route protection for role-based access · `src/middleware.ts`

### Backend platform

Supabase schema, auth, storage, and payment integration

- [Supabase client](https://github.com/hectordev2/corrales-web/blob/main/src/lib/supabase-server.ts): server client · Server-side Supabase access wrapper · `src/lib/supabase-server.ts`
- [DB types](https://github.com/hectordev2/corrales-web/blob/main/src/types/database.types.ts): generated types · Typed schema bindings for the frontend · `src/types/database.types.ts`
- [Migrations](https://github.com/hectordev2/corrales-web/tree/main/supabase/migrations): SQL schema · Database schema, RPCs, RLS policies, triggers, and storage setup · `supabase/migrations`
- [Product images](https://github.com/hectordev2/corrales-web/blob/main/supabase/migrations/20260409000000_product_images_storage.sql): storage bucket · Public product image bucket in Supabase Storage · `supabase/migrations/20260409000000_product_images_storage.sql`
- **Culqi**: payment provider · External payment processing provider

## Connections

- Root layout → Public site: wraps · Global shell contains the public route group
- Root layout → Admin area: wraps · Global shell contains the admin route group
- Root layout → Delivery area: wraps · Global shell contains the delivery route group
- Root layout → Login: renders · Global app shell also serves the login page
- Public site → Home view: hosts · Public pages render the home experience
- Public site → Menu view: hosts · Public pages render the menu/catalog experience
- Public site → Checkout flow: hosts · Public pages render checkout
- Public site → Reservations: hosts · Public pages render reservation booking
- Admin area → Admin dashboard: hosts · Admin route group renders operational screens
- Delivery area → Delivery view: hosts · Delivery route group renders courier screens
- Site chrome → Home view: shared with · Common navigation and page chrome appear across public views
- Site chrome → Menu view: shared with · Common navigation and page chrome appear across public views
- Menu view → Cart store: uses · Menu browsing writes into client cart state
- Checkout flow → Cart store: reads · Checkout consumes the current cart contents
- Checkout flow → Orders API: submits · Checkout creates an order through the order layer
- Reservations → Reservations API: submits · Reservation form persists booking data
- Admin dashboard → Admin API: manages · Admin screens update orders and assignments
- Admin dashboard → Products API: manages · Admin product CRUD goes through the product layer
- Delivery view → Delivery API: queries · Courier view reads assigned orders and updates status
- Login → User store: updates · Login/session state is reflected locally
- Route guard → Admin area: protects · Role-based route protection for admin paths
- Route guard → Delivery area: protects · Role-based route protection for delivery paths
- Products API → Supabase client: calls · Product operations use the server-side Supabase client
- Orders API → Supabase client: calls · Order creation and reads use Supabase
- Admin API → Supabase client: calls · Admin mutations go through Supabase
- Delivery API → Supabase client: calls · Delivery operations go through Supabase
- Reservations API → Supabase client: calls · Reservation persistence uses Supabase
- Supabase client → DB types: typed by · Data access is aligned with generated database types
- Supabase client → Migrations: backed by · Supabase client reads and writes the migrated schema
- Migrations → Product images: defines · Migrations provision public product image storage
- Products API → Product images: uploads · Product images are stored in Supabase Storage
- Orders API → Culqi: charges · Payment flow hands off to Culqi via the charge API
- Charge API → Culqi: integrates · API route mediates payment provider interaction
- Charge API → Orders API: completes · Payment completion is tied to the order workflow