# jdavidcruzc/infocom-ilo architecture

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

- Interactive diagram: https://gitdiagram.com/jdavidcruzc/infocom-ilo
- Repository: https://github.com/jdavidcruzc/infocom-ilo

## Overview

#### Purpose and Runtime
INFOCOM SOLUCIONES is a full-stack commercial-management platform for a computer retailer and repair shop: public e-commerce, POS/backoffice, technical-service workflow, accounting, inventory, staff, and reporting. It is a React 18/TypeScript SPA built by Vite and deployed to Vercel; Supabase supplies PostgreSQL, Auth, Storage, Realtime, and Edge Functions.

Entry points: `src/main.tsx` mounts the application; `src/App.tsx` composes routing and top-level feature access. SPA deep-link handling is deployed through `vercel.json`.

#### Feature Segmentation and Navigation
The UI is organized by business feature rather than a generic pages layer:
- Public shop: home, catalog, product details, company/contact/account pages in `src/features/shop/pages/HomePage.tsx`, `src/features/shop/pages/CatalogPage.tsx`, `src/features/shop/pages/ProductDetailPage.tsx`.
- Purchase journey: shared cart state and drawer, then checkout at `src/hooks/use-cart.ts`, `src/features/cart/components/CartDrawer.tsx`, `src/features/checkout/pages/CheckoutPage.tsx`.
- Protected backoffice is mounted in `src/features/admin/layout/AdminLayout.tsx` and consists of independently scoped operational pages.

#### Identity, Authorization, and Security Boundary
Supabase Auth establishes browser sessions; frontend hooks expose identity and roles through `src/features/auth/hooks/useAuth.tsx` and `src/features/auth/hooks/usePermissions.tsx`. Route guards enforce authenticated and permission-scoped admin access in `src/features/auth/components/ProtectedRoute.tsx` and `src/features/auth/components/PermissionRoute.tsx`.

The browser is not the final authorization boundary: Supabase PostgreSQL Row Level Security, represented by the ordered SQL history under `supabase/migrations/`, must govern sensitive reads and writes. Input normalization/sanitization is centralized in `src/lib/sanitize.ts`.

#### Commerce, Inventory, and Finance Operations
Admin operations center on product/catalog maintenance, sales, purchasing, inventory movement, and accounting:
- Catalog and stock definition: `src/features/admin/pages/ProductsPage.tsx`, `src/features/admin/pages/CategoriesPage.tsx`, `src/features/admin/pages/KardexPage.tsx`.
- POS and transactions: `src/features/admin/pages/SalesPage.tsx`, with print output through `src/features/admin/components/PrintReceipt.tsx`.
- Unified financial records, receivables, and export-oriented accounting: `src/features/admin/pages/AccountingPage.tsx`, `src/features/admin/components/SendToAccountingDialog.tsx`.

The intended transaction flow is sale/checkout → persisted transaction and item records → stock/Kardex update → receipt/accounting representation. Database triggers and constraints defined in migrations are an important consistency boundary; frontend state must not become the source of truth.

#### Technical Service and Staff Operations
Technical service is a separate operational domain rather than a shop extension. Reception and lifecycle management are driven from `src/features/admin/pages/ReceptionPage.tsx`; encapsulated domain operations reside in `src/features/admin/services/technicalService.ts`; supporting transaction history is surfaced by `src/features/admin/components/TransactionHistoryDialog.tsx`. This supports intake, diagnosis/quotation, parts, repair status, delivery, and associated payments.

Internal workforce workflows include staff records, role setup, attendance, and appointments in `src/features/admin/pages/StaffPage.tsx`, `src/features/admin/pages/AttendancePage.tsx`, and `src/features/admin/pages/AppointmentsPage.tsx`.

#### Supabase Integration and External Services
The typed browser client is the main data-access gateway at `src/integrations/supabase/client.ts`, with generated/domain database types in `src/integrations/supabase/types.ts`. It communicates with Supabase via authenticated HTTPS/PostgREST, Storage for uploaded assets, and Realtime for shared operational updates.

Privileged or third-party work is isolated to Supabase Edge Functions: `supabase/functions/create-staff-account/index.ts` creates staff accounts, while `supabase/functions/dni-lookup/index.ts` performs DNI lookup against an external service. WhatsApp is used as an outbound/deep-link communication channel from shop and service flows, including `src/features/shop/components/WhatsAppButton.tsx`.

#### Presentation System and Deployment
Reusable primitives are housed in `src/components/ui/`; feature pages compose these instead of owning base controls. Global visual state is provided by `src/features/theme/ThemeProvider.tsx` and `src/features/theme/FloatingThemeToggle.tsx`. Shared cart and business utilities live outside feature UI at `src/lib/cart.ts` and `src/lib/types.ts`.

Infrastructure is serverless: Vercel hosts the static SPA/CDN deployment, while Supabase owns backend persistence and execution. Schema evolution is migration-driven under `supabase/migrations/`; changes affecting transactions, roles, inventory, or service workflows should be planned as coordinated frontend, RLS/schema, and data-migration work.

Main entry points: [`src/integrations/supabase/client.ts`](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/integrations/supabase/client.ts) (Typed Supabase client), [`src/features/admin/layout/AdminLayout.tsx`](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/layout/AdminLayout.tsx) (Admin shell), [`src/App.tsx`](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/App.tsx) (App routing), [`src/features/shop/pages/HomePage.tsx`](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/shop/pages/HomePage.tsx) (Public shop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_main["Application mount<br/>React entry<br/>[main.tsx]"]
  node_app["App routing<br/>route composition<br/>[App.tsx]"]
  node_shop["Public shop<br/>shop pages<br/>[HomePage.tsx]"]
  node_cart_checkout["Cart &amp; checkout<br/>purchase flow<br/>[use-cart.ts]"]
  node_auth_guards["Auth &amp; route guards<br/>identity access<br/>[useAuth.tsx]"]
  node_ui_system["UI &amp; theme system<br/>presentation primitives"]
end

subgraph group_operations["Business Operations"]
  node_admin_layout["Admin shell<br/>protected layout<br/>[AdminLayout.tsx]"]
  node_catalog_inventory["Catalog &amp; inventory<br/>operations UI<br/>[ProductsPage.tsx]"]
  node_sales["POS &amp; sales<br/>transaction UI<br/>[SalesPage.tsx]"]
  node_accounting["Accounting<br/>finance UI<br/>[AccountingPage.tsx]"]
  node_technical_service["Technical service<br/>service workflow"]
  node_staff["Staff operations<br/>workforce UI<br/>[StaffPage.tsx]"]
end

subgraph group_supabase["Supabase Backend"]
  node_supabase_client["Typed Supabase client<br/>browser data gateway<br/>[client.ts]"]
  node_auth["Supabase Auth<br/>identity service"]
  node_database[("PostgreSQL data<br/>transactional database")]
  node_migrations_rls["Schema, RLS &amp; triggers<br/>consistency boundary"]
  node_realtime_storage["Realtime &amp; Storage<br/>Supabase services"]
  node_edge_functions{{"Edge Functions<br/>privileged integration<br/>[index.ts]"}}
end

subgraph group_external["Deployment &amp; External"]
  node_vercel["Vercel SPA hosting<br/>static deployment<br/>[vercel.json]"]
  node_dni_service["DNI lookup service<br/>external API"]
  node_whatsapp["WhatsApp<br/>communication channel<br/>[WhatsAppButton.tsx]"]
end

node_main -->|"mounts"| node_app
node_app -->|"public routes"| node_shop
node_app -->|"checkout route"| node_cart_checkout
node_app -->|"protects admin access"| node_auth_guards
node_auth_guards -->|"authorized access"| node_admin_layout
node_admin_layout -->|"hosts"| node_catalog_inventory
node_admin_layout -->|"hosts"| node_sales
node_admin_layout -->|"hosts"| node_accounting
node_admin_layout -->|"hosts"| node_technical_service
node_admin_layout -->|"hosts"| node_staff
node_shop -->|"adds products"| node_cart_checkout
node_cart_checkout -->|"persists checkout"| node_supabase_client
node_catalog_inventory -->|"manages stock"| node_supabase_client
node_sales -->|"persists transactions"| node_supabase_client
node_accounting -->|"reads financial records"| node_supabase_client
node_technical_service -->|"persists service lifecycle"| node_supabase_client
node_staff -->|"provisions accounts"| node_edge_functions
node_auth_guards -->|"reads session and roles"| node_auth
node_supabase_client -->|"authenticated data access"| node_database
node_supabase_client -->|"subscribes and uploads"| node_realtime_storage
node_migrations_rls -->|"defines schema and enforcement"| node_database
node_database -.->|"transaction updates stock/Kardex"| node_catalog_inventory
node_database -.->|"transaction feeds accounting"| node_accounting
node_edge_functions -->|"creates staff identities"| node_auth
node_edge_functions -->|"performs lookup"| node_dni_service
node_vercel -->|"serves SPA"| node_main
node_shop -->|"opens contact channel"| node_whatsapp
node_technical_service -->|"sends service communication"| node_whatsapp
node_app -->|"composes shared presentation"| node_ui_system

click node_main "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/main.tsx"
click node_app "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/App.tsx"
click node_shop "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/shop/pages/HomePage.tsx"
click node_cart_checkout "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/hooks/use-cart.ts"
click node_auth_guards "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/auth/hooks/useAuth.tsx"
click node_admin_layout "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/layout/AdminLayout.tsx"
click node_catalog_inventory "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/ProductsPage.tsx"
click node_sales "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/SalesPage.tsx"
click node_accounting "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/AccountingPage.tsx"
click node_technical_service "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/services/technicalService.ts"
click node_staff "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/StaffPage.tsx"
click node_supabase_client "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/integrations/supabase/client.ts"
click node_edge_functions "https://github.com/jdavidcruzc/infocom-ilo/blob/main/supabase/functions/create-staff-account/index.ts"
click node_vercel "https://github.com/jdavidcruzc/infocom-ilo/blob/main/vercel.json"
click node_whatsapp "https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/shop/components/WhatsAppButton.tsx"

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_shop,node_cart_checkout,node_auth_guards,node_ui_system toneBlue
class node_admin_layout,node_catalog_inventory,node_sales,node_accounting,node_technical_service,node_staff toneAmber
class node_supabase_client,node_auth,node_database,node_migrations_rls,node_realtime_storage,node_edge_functions toneMint
class node_vercel,node_dni_service,node_whatsapp toneRose
```

## Components

### React SPA

Vite-built browser application.

- [Application mount](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/main.tsx): React entry · `src/main.tsx`
- [App routing](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/App.tsx): route composition · Composes public, checkout, and protected feature access. · `src/App.tsx`
- [Public shop](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/shop/pages/HomePage.tsx): shop pages · Home, catalog, product detail, and account-facing pages. · `src/features/shop/pages/HomePage.tsx`
- [Cart & checkout](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/hooks/use-cart.ts): purchase flow · Shared cart state feeds checkout and persisted sales. · `src/hooks/use-cart.ts`
- [Auth & route guards](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/auth/hooks/useAuth.tsx): identity access · Exposes sessions and roles, then guards admin routes. · `src/features/auth/hooks/useAuth.tsx`
- **UI & theme system**: presentation primitives · Shared controls and global visual state.

### Business Operations

Protected operational feature domains.

- [Admin shell](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/layout/AdminLayout.tsx): protected layout · Mount point for backoffice domains. · `src/features/admin/layout/AdminLayout.tsx`
- [Catalog & inventory](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/ProductsPage.tsx): operations UI · Products, categories, and Kardex stock movement. · `src/features/admin/pages/ProductsPage.tsx`
- [POS & sales](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/SalesPage.tsx): transaction UI · Records sales and produces printable receipts. · `src/features/admin/pages/SalesPage.tsx`
- [Accounting](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/AccountingPage.tsx): finance UI · Financial records, receivables, and accounting export. · `src/features/admin/pages/AccountingPage.tsx`
- [Technical service](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/services/technicalService.ts): service workflow · Reception, repair lifecycle, parts, delivery, and payments. · `src/features/admin/services/technicalService.ts`
- [Staff operations](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/admin/pages/StaffPage.tsx): workforce UI · Staff, roles, attendance, and appointments. · `src/features/admin/pages/StaffPage.tsx`

### Supabase Backend

Persistence, authorization, realtime, and server-side execution.

- [Typed Supabase client](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/integrations/supabase/client.ts): browser data gateway · Authenticated access to database, storage, and realtime. · `src/integrations/supabase/client.ts`
- **Supabase Auth**: identity service
- **PostgreSQL data**: transactional database · Canonical records for commerce, inventory, finance, service, and staff.
- **Schema, RLS & triggers**: consistency boundary · Migration-defined authorization, constraints, and transaction consistency.
- **Realtime & Storage**: Supabase services · Shared operational updates and uploaded assets.
- [Edge Functions](https://github.com/jdavidcruzc/infocom-ilo/blob/main/supabase/functions/create-staff-account/index.ts): privileged integration · Creates staff accounts and performs DNI lookup. · `supabase/functions/create-staff-account/index.ts`

### Deployment & External

- [Vercel SPA hosting](https://github.com/jdavidcruzc/infocom-ilo/blob/main/vercel.json): static deployment · Hosts the SPA with deep-link handling. · `vercel.json`
- **DNI lookup service**: external API
- [WhatsApp](https://github.com/jdavidcruzc/infocom-ilo/blob/main/src/features/shop/components/WhatsAppButton.tsx): communication channel · Outbound shop and service communication deep links. · `src/features/shop/components/WhatsAppButton.tsx`

## Connections

- Application mount → App routing: mounts
- App routing → Public shop: public routes
- App routing → Cart & checkout: checkout route
- App routing → Auth & route guards: protects admin access
- Auth & route guards → Admin shell: authorized access
- Admin shell → Catalog & inventory: hosts
- Admin shell → POS & sales: hosts
- Admin shell → Accounting: hosts
- Admin shell → Technical service: hosts
- Admin shell → Staff operations: hosts
- Public shop → Cart & checkout: adds products
- Cart & checkout → Typed Supabase client: persists checkout
- Catalog & inventory → Typed Supabase client: manages stock
- POS & sales → Typed Supabase client: persists transactions
- Accounting → Typed Supabase client: reads financial records
- Technical service → Typed Supabase client: persists service lifecycle
- Staff operations → Edge Functions: provisions accounts
- Auth & route guards → Supabase Auth: reads session and roles
- Typed Supabase client → PostgreSQL data: authenticated data access
- Typed Supabase client → Realtime & Storage: subscribes and uploads
- Schema, RLS & triggers → PostgreSQL data: defines schema and enforcement
- PostgreSQL data → Catalog & inventory: transaction updates stock/Kardex
- PostgreSQL data → Accounting: transaction feeds accounting
- Edge Functions → Supabase Auth: creates staff identities
- Edge Functions → DNI lookup service: performs lookup
- Vercel SPA hosting → Application mount: serves SPA
- Public shop → WhatsApp: opens contact channel
- Technical service → WhatsApp: sends service communication
- App routing → UI & theme system: composes shared presentation