ajperezcossio/diagramas

1. System shape

MiniMarketWeb is a single-page React application for a minimarket business, not a separate frontend/backend monolith. The runtime architecture is: browser UI → client state → service layer → Supabase/PostgreSQL. Most business logic lives in the frontend services and hooks, with Supabase acting as the external data/auth backend.

2. Top-level partitioning

The codebase is organized by feature and role. src/pages/ contains role-specific screens for:

• cliente for shopping and loyalty

• empleado for operations and admin workflows

• cajero for sales processing

• repartidor for delivery handling

• root pages for login/register/404

This role-based partitioning is the main structural boundary an architecture diagram should show.

3. Presentation layer

src/components/ holds cross-cutting UI pieces like Layout, ProtectedRoute, LoadingScreen, and DataDiagnostics. src/pages/** contains the actual screens and some local subcomponents/modals. Routing is centralized in src/App.jsx and bootstrapped from src/main.jsx.

4. State management

Application state is handled with Zustand stores in src/store/:

• useAuthStore for session, profile, and role

• useCartStore for shopping cart state and persistence

• useThemeStore for UI theme

These stores are the main client-side coordination layer between pages and services. Session/cart state is persisted locally, so the app can survive reloads without re-fetching everything.

5. Business logic / service layer

src/lib/ is the core business layer. It contains focused services for:

• products/data access: dataService.js

• loyalty: lealtadService.js

• promotions: promocionesService.js

• returns: devolucionesService.js

• payroll: nominaService.js

• shifts: turnosService.js

These services encapsulate the business rules used by multiple screens and keep pages thinner. currencyFormatter.js is a shared utility, not a domain service.

6. Backend boundary

The only backend integration visible in the repo is Supabase via src/lib/supabase.js. That file is important because it abstracts between a real Supabase client and a mock/local fallback for development/testing. So the architectural boundary is not “frontend talks to custom API,” but “frontend services talk directly to Supabase.”

7. Authentication and authorization flow

Authentication is handled through useAuthStore and enforced at the routing layer with ProtectedRoute. The app uses RBAC with roles like client, employee, admin, cashier, and delivery person. After login, the store loads the user profile, persists session state, and routes the user to the correct dashboard.

8. Core business workflows

The most important data flows are:

• Catalog → Cart → Promotions → Sales → Loyalty

• Sales → Delivery/Reparto for home delivery orders

• Sales → Returns for post-sale returns

• Attendance/Shifts → Payroll for HR calculations

These are the main cross-module dependencies and should be central in any system diagram.

9. Domain modules reflected in the UI

The UI exposes several business capabilities that map to separate bounded areas:

• product/inventory management

• checkout and payment processing

• loyalty points and redemptions

• promotional pricing and coupons

• delivery assignment and tracking

• returns approval and reimbursement

• attendance, shifts, and payroll

• task assignment and operational dashboards

Even though everything is in one frontend app, these modules are logically distinct and interact through services and shared data tables.

10. Database and schema assets

The database/ folder contains SQL scripts such as schema_extensiones.sql and actualizar_precios_bs.sql. This indicates the project expects a structured relational schema in Supabase/PostgreSQL, with extension tables for loyalty, promotions, payroll, and other operational areas. Those scripts are part of the data-definition boundary, not application runtime code.

11. Testing structure

The repo has a mature test layout under test/:

• unit tests for stores, services, and utilities

• integration tests for auth, cart, loyalty, returns, and protected routes

• e2e flows for login, registration, and cart

This suggests the architecture is designed around testable service/store boundaries rather than only UI snapshot testing.

12. Deployment and infrastructure

vercel.json shows the production delivery target is Vercel. The infra/ folder contains Vagrant/Ansible scripts, but the README suggests this is supplemental infrastructure rather than the main runtime path. So the production architecture is: static React bundle on Vercel, Supabase as backend/data, with optional local mock and infra tooling for setup.

13. What to emphasize in a diagram

A faithful architecture diagram should show:

• Browser SPA as the main entry point

• Role-based route guards

• Zustand as the shared client state hub

• Service layer as the business logic boundary

• Supabase/PostgreSQL as external persistence/auth

• Separate domain areas for sales, loyalty, promotions, returns, delivery, HR, and inventory

• SQL migration/assets as offline schema support

• Vercel as deployment host

14. Important architectural nuance

This repository is best understood as a frontend-centric business application with backend-as-a-service, not as a traditional multi-tier server app. The “backend” responsibilities are largely pushed into Supabase and frontend service modules, while the React app orchestrates workflows and enforces role-based access.