hectordev2/corrales-web

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.