# ajperezcossio/diagramas architecture

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

- Interactive diagram: https://gitdiagram.com/ajperezcossio/diagramas
- Repository: https://github.com/ajperezcossio/diagramas

## Overview

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.

Main entry points: [`MiniMarketWeb-final/src/App.jsx`](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/App.jsx) (App), [`MiniMarketWeb-final/src/lib/supabase.js`](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/supabase.js) (Supabase), [`MiniMarketWeb-final/src/pages/cliente/Dashboard.jsx`](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/cliente/Dashboard.jsx) (Cliente), [`MiniMarketWeb-final/src/lib/dataService.js`](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/dataService.js) (Data Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main["main.jsx<br/>bootstrap<br/>[main.jsx]"]
  node_app["App<br/>router<br/>[App.jsx]"]
  node_layout["Layout<br/>shell UI<br/>[Layout.jsx]"]
  node_protected_route{{"Protected Route<br/>auth guard<br/>[ProtectedRoute.jsx]"}}
  node_auth_pages["Auth Pages<br/>public screens<br/>[LoginPage.jsx]"]
  node_client_area["Cliente<br/>role area<br/>[Dashboard.jsx]"]
  node_employee_area["Empleado<br/>ops area<br/>[Dashboard.jsx]"]
  node_cashier_area["Cajero<br/>checkout area<br/>[Cajero.jsx]"]
  node_delivery_area["Repartidor<br/>delivery area<br/>[Repartidor.jsx]"]
end

subgraph group_state["State"]
  node_auth_store[("Auth Store<br/>zustand store<br/>[useAuthStore.js]")]
  node_cart_store[("Cart Store<br/>zustand store<br/>[useCartStore.js]")]
  node_theme_store[("Theme Store<br/>zustand store<br/>[useThemeStore.js]")]
end

subgraph group_services["Services"]
  node_data_service["Data Service<br/>[dataService.js]"]
  node_promotions_service["Promotions<br/>domain service"]
  node_loyalty_service["Loyalty<br/>domain service<br/>[lealtadService.js]"]
  node_returns_service["Returns<br/>domain service"]
  node_payroll_service["Payroll<br/>domain service<br/>[nominaService.js]"]
  node_shifts_service["Shifts<br/>domain service<br/>[turnosService.js]"]
  node_hooks["Data Hooks<br/>react hooks"]
end

subgraph group_data["Data Boundary"]
  node_supabase[("Supabase<br/>backend adapter<br/>[supabase.js]")]
  node_db_scripts["SQL Assets<br/>schema scripts"]
end

subgraph group_delivery["Delivery"]
  node_tests["Tests<br/>verification suite<br/>[setup.js]"]
  node_vercel["Vercel<br/>deployment<br/>[vercel.json]"]
  node_infra["Infra<br/>local setup"]
end

node_main -->|"boots"| node_app
node_app -->|"wraps"| node_layout
node_app -->|"guards"| node_protected_route
node_app -->|"exposes"| node_auth_pages
node_app -->|"routes"| node_client_area
node_app -->|"routes"| node_employee_area
node_app -->|"routes"| node_cashier_area
node_app -->|"routes"| node_delivery_area
node_protected_route -->|"reads"| node_auth_store
node_layout -->|"uses"| node_theme_store
node_layout -->|"uses"| node_auth_store
node_client_area -->|"reads/writes"| node_cart_store
node_client_area -->|"loads"| node_data_service
node_client_area -->|"uses"| node_loyalty_service
node_client_area -->|"uses"| node_promotions_service
node_client_area -->|"uses"| node_returns_service
node_employee_area -->|"manages"| node_data_service
node_employee_area -->|"uses"| node_returns_service
node_employee_area -->|"uses"| node_payroll_service
node_employee_area -->|"uses"| node_shifts_service
node_cashier_area -->|"uses"| node_cart_store
node_cashier_area -->|"sells"| node_data_service
node_cashier_area -->|"applies"| node_promotions_service
node_cashier_area -->|"awards"| node_loyalty_service
node_delivery_area -->|"uses"| node_shifts_service
node_delivery_area -->|"tracks"| node_data_service
node_hooks -->|"orchestrates"| node_data_service
node_hooks -->|"initializes"| node_auth_store
node_data_service -->|"reads/writes"| node_supabase
node_promotions_service -->|"reads/writes"| node_supabase
node_loyalty_service -->|"reads/writes"| node_supabase
node_returns_service -->|"reads/writes"| node_supabase
node_payroll_service -->|"reads/writes"| node_supabase
node_shifts_service -->|"reads/writes"| node_supabase
node_supabase -.->|"schema"| node_db_scripts
node_tests -->|"verifies"| node_auth_store
node_tests -->|"verifies"| node_cart_store
node_tests -->|"verifies"| node_promotions_service
node_tests -->|"verifies"| node_loyalty_service
node_tests -->|"verifies"| node_protected_route
node_vercel -->|"hosts"| node_main
node_infra -.->|"supports"| node_supabase

click node_main "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/main.jsx"
click node_app "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/App.jsx"
click node_layout "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/components/Layout.jsx"
click node_protected_route "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/components/ProtectedRoute.jsx"
click node_auth_pages "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/LoginPage.jsx"
click node_client_area "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/cliente/Dashboard.jsx"
click node_employee_area "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/empleado/Dashboard.jsx"
click node_cashier_area "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/cajero/Cajero.jsx"
click node_delivery_area "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/repartidor/Repartidor.jsx"
click node_auth_store "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/store/useAuthStore.js"
click node_cart_store "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/store/useCartStore.js"
click node_theme_store "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/store/useThemeStore.js"
click node_data_service "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/dataService.js"
click node_promotions_service "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/promocionesService.js"
click node_loyalty_service "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/lealtadService.js"
click node_returns_service "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/devolucionesService.js"
click node_payroll_service "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/nominaService.js"
click node_shifts_service "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/turnosService.js"
click node_hooks "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/hooks/useInitializeData.js"
click node_supabase "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/supabase.js"
click node_db_scripts "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/database/schema_extensiones.sql"
click node_tests "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/test/setup.js"
click node_vercel "https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/vercel.json"
click node_infra "https://github.com/ajperezcossio/diagramas/tree/main/infra/Vagrantfile"

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_main,node_app,node_layout,node_protected_route,node_auth_pages,node_client_area,node_employee_area,node_cashier_area,node_delivery_area toneBlue
class node_auth_store,node_cart_store,node_theme_store toneAmber
class node_data_service,node_promotions_service,node_loyalty_service,node_returns_service,node_payroll_service,node_shifts_service,node_hooks toneMint
class node_supabase,node_db_scripts toneRose
class node_tests,node_vercel,node_infra toneIndigo
```

## Components

### Presentation

React entry, routing, layouts, and role screens

- [main.jsx](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/main.jsx): bootstrap · Vite entrypoint that mounts the app · `MiniMarketWeb-final/src/main.jsx`
- [App](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/App.jsx): router · Central route and role navigation setup · `MiniMarketWeb-final/src/App.jsx`
- [Layout](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/components/Layout.jsx): shell UI · Shared application shell and navigation chrome · `MiniMarketWeb-final/src/components/Layout.jsx`
- [Protected Route](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/components/ProtectedRoute.jsx): auth guard · Route guard enforcing session and role access · `MiniMarketWeb-final/src/components/ProtectedRoute.jsx`
- [Auth Pages](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/LoginPage.jsx): public screens · Login and registration entry screens · `MiniMarketWeb-final/src/pages/LoginPage.jsx`
- [Cliente](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/cliente/Dashboard.jsx): role area · Shopping, cart, loyalty, orders, and profile flows · `MiniMarketWeb-final/src/pages/cliente/Dashboard.jsx`
- [Empleado](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/empleado/Dashboard.jsx): ops area · Inventory, tasks, attendance, returns, and admin workflows · `MiniMarketWeb-final/src/pages/empleado/Dashboard.jsx`
- [Cajero](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/cajero/Cajero.jsx): checkout area · Sales processing and payment handling · `MiniMarketWeb-final/src/pages/cajero/Cajero.jsx`
- [Repartidor](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/pages/repartidor/Repartidor.jsx): delivery area · Delivery assignment, routes, and shift views · `MiniMarketWeb-final/src/pages/repartidor/Repartidor.jsx`

### State

Client-side coordination with persisted stores

- [Auth Store](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/store/useAuthStore.js): zustand store · Session, profile, and role state with persistence · `MiniMarketWeb-final/src/store/useAuthStore.js`
- [Cart Store](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/store/useCartStore.js): zustand store · Cart contents, checkout state, and persistence · `MiniMarketWeb-final/src/store/useCartStore.js`
- [Theme Store](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/store/useThemeStore.js): zustand store · UI theme state · `MiniMarketWeb-final/src/store/useThemeStore.js`

### Services

Business logic and domain workflows

- [Data Service](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/dataService.js): catalog/data service · Shared data access for products and core entities · `MiniMarketWeb-final/src/lib/dataService.js`
- [Promotions](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/promocionesService.js): domain service · Promotional pricing and coupon rules · `MiniMarketWeb-final/src/lib/promocionesService.js`
- [Loyalty](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/lealtadService.js): domain service · Points, redemptions, and loyalty rules · `MiniMarketWeb-final/src/lib/lealtadService.js`
- [Returns](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/devolucionesService.js): domain service · Return approval and reimbursement logic · `MiniMarketWeb-final/src/lib/devolucionesService.js`
- [Payroll](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/nominaService.js): domain service · Payroll calculations and employee compensation workflows · `MiniMarketWeb-final/src/lib/nominaService.js`
- [Shifts](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/turnosService.js): domain service · Shift scheduling and attendance coordination · `MiniMarketWeb-final/src/lib/turnosService.js`
- [Data Hooks](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/hooks/useInitializeData.js): react hooks · Initialization and data-loading coordination layer · `MiniMarketWeb-final/src/hooks/useInitializeData.js`

### Data Boundary

Supabase backend and database assets

- [Supabase](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/src/lib/supabase.js): backend adapter · Supabase client with mock/local fallback · `MiniMarketWeb-final/src/lib/supabase.js`
- [SQL Assets](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/database/schema_extensiones.sql): schema scripts · Database schema extensions and price update scripts · `MiniMarketWeb-final/database/schema_extensiones.sql`

### Delivery

Build, deployment, and test assets

- [Tests](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/test/setup.js): verification suite · Unit, integration, and e2e coverage around stores, services, and routes · `MiniMarketWeb-final/test/setup.js`
- [Vercel](https://github.com/ajperezcossio/diagramas/blob/main/MiniMarketWeb-final/vercel.json): deployment · Production hosting target for the SPA · `MiniMarketWeb-final/vercel.json`
- [Infra](https://github.com/ajperezcossio/diagramas/tree/main/infra/Vagrantfile): local setup · Vagrant and Ansible support for local environment setup · `infra/Vagrantfile`

## Connections

- main.jsx → App: boots · Application entry mounts the router
- App → Layout: wraps · Routes are rendered within the shared shell
- App → Protected Route: guards · Private routes are protected by role and session checks
- App → Auth Pages: exposes · Public entry screens for login and registration
- App → Cliente: routes · Client role dashboards and workflows
- App → Empleado: routes · Employee and admin workflows
- App → Cajero: routes · Cashier checkout screens
- App → Repartidor: routes · Delivery role screens
- Protected Route → Auth Store: reads · Access control depends on session and role state
- Layout → Theme Store: uses · Shell reacts to theme state
- Layout → Auth Store: uses · Shell adapts to authenticated user context
- Cliente → Cart Store: reads/writes · Shopping and checkout use shared cart state
- Cliente → Data Service: loads · Catalog and product data are fetched through services
- Cliente → Loyalty: uses · Client loyalty views and redemptions
- Cliente → Promotions: uses · Promotion-aware shopping flows
- Cliente → Returns: uses · Customer return requests and status
- Empleado → Data Service: manages · Inventory, products, users, and operational data
- Empleado → Returns: uses · Return processing workflows
- Empleado → Payroll: uses · Payroll administration screens
- Empleado → Shifts: uses · Attendance and shift management
- Cajero → Cart Store: uses · Checkout state and sale composition
- Cajero → Data Service: sells · Sales processing depends on shared product data
- Cajero → Promotions: applies · Promotions affect pricing at checkout
- Cajero → Loyalty: awards · Sales feed loyalty points and redemptions
- Repartidor → Shifts: uses · Shift and attendance views for delivery staff
- Repartidor → Data Service: tracks · Delivery orders and assignments use shared data
- Data Hooks → Data Service: orchestrates · Data loading and initialization flow
- Data Hooks → Auth Store: initializes · Bootstraps session and profile state
- Data Service → Supabase: reads/writes · Core data access goes through Supabase
- Promotions → Supabase: reads/writes · Promotion rules and tables live in Supabase
- Loyalty → Supabase: reads/writes · Loyalty data is stored remotely
- Returns → Supabase: reads/writes · Return records and reimbursements persist remotely
- Payroll → Supabase: reads/writes · Payroll calculations use backend data
- Shifts → Supabase: reads/writes · Shift and attendance records persist remotely
- Supabase → SQL Assets: schema · Database behavior is supported by SQL assets
- Tests → Auth Store: verifies · Store behavior and auth flow coverage
- Tests → Cart Store: verifies · Cart persistence and business logic coverage
- Tests → Promotions: verifies · Promotion rules are covered by tests
- Tests → Loyalty: verifies · Loyalty workflows are covered by tests
- Tests → Protected Route: verifies · Route access control is tested
- Vercel → main.jsx: hosts · Production deployment serves the SPA bundle
- Infra → Supabase: supports · Local setup and environment tooling support the backend boundary