# franciscogb03/tiendita-pos architecture

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

- Interactive diagram: https://gitdiagram.com/franciscogb03/tiendita-pos
- Repository: https://github.com/franciscogb03/tiendita-pos

## Overview

Tiendita POS is an offline-first point-of-sale system. A cashier signs in, configures a terminal, selects products, builds a cart, and completes payment; sales are sent to the API or queued locally for later synchronization. The backend also provides product, terminal-validation, and protected daily-report endpoints. The graph includes authentication, checkout, offline recovery, and reporting; some backend handlers and frontend modules were not excerpted, so their internal behavior and unsupported connections are omitted.

Main entry points: [`frontend/src/pages/POSPage.tsx`](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/pages/POSPage.tsx) (POS page), [`backend/internal/router/router.go`](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/router/router.go) (HTTP routes), [`frontend/src/lib/api.ts`](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/lib/api.ts) (HTTP client), [`frontend/src/hooks/useSyncQueue.ts`](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useSyncQueue.ts) (Sync queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["POS frontend"]
  node_app["App routing<br/>[App.tsx]"]
  node_login["Login page<br/>[LoginPage.tsx]"]
  node_pos["POS page<br/>[POSPage.tsx]"]
  node_products_ui["Product grid<br/>[ProductGrid.tsx]"]
  node_cart_ui["Cart ticket<br/>[CartTicket.tsx]"]
  node_payment_ui["Payment modal<br/>[PaymentModal.tsx]"]
  node_terminal["Terminal setup<br/>[useTerminalId.ts]"]
  node_api_client["HTTP client<br/>[api.ts]"]
end

subgraph group_backend["POS API"]
  node_api_server["API server<br/>[main.go]"]
  node_router["HTTP routes<br/>[router.go]"]
end

subgraph group_auth["Authentication"]
  node_auth_hook["Session state<br/>[useAuth.ts]"]
  node_auth_handler["Login handler<br/>[auth.go]"]
  node_auth_service["Auth service<br/>[auth_service.go]"]
  node_user_repo["User repository<br/>[user_repository.go]"]
end

subgraph group_sales["Sales and sync"]
  node_sale_service["Sale service<br/>[saleService.ts]"]
  node_sync_queue["Sync queue<br/>[useSyncQueue.ts]"]
  node_network["Network status"]
  node_local_db[("Local sales store<br/>[db.ts]")]
  node_sale_handler["Sale handler<br/>[sale.go]"]
  node_backend_sale_service["Sale service<br/>[sale_service.go]"]
  node_sale_repo["Sale repository<br/>[sale_repository.go]"]
end

subgraph group_catalog["Catalog and reports"]
  node_product_service["Product service<br/>[productService.ts]"]
  node_product_hook["Product state<br/>[useProducts.ts]"]
  node_products_handler["Products handler<br/>[products.go]"]
  node_terminal_handler["Terminal handler<br/>[terminal.go]"]
  node_report_handler["Report handler<br/>[report.go]"]
  node_report_repo["Report repository"]
end

node_cashier(("Cashier"))
node_postgres[("PostgreSQL")]

node_cashier -->|"uses"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_pos
node_login -->|"authenticates via"| node_api_client
node_pos -->|"renders"| node_products_ui
node_pos -->|"renders"| node_cart_ui
node_pos -->|"renders"| node_payment_ui
node_pos -->|"loads terminal"| node_terminal
node_pos -->|"submits sale"| node_sale_service
node_pos -->|"tracks sync"| node_sync_queue
node_pos -->|"reads status"| node_network
node_pos -->|"reads session"| node_auth_hook
node_products_ui -.->|"uses products"| node_product_hook
node_product_hook -->|"loads products"| node_product_service
node_product_service -->|"requests products"| node_api_client
node_terminal -->|"validates terminal"| node_api_client
node_sale_service -->|"posts sale"| node_api_client
node_sale_service -->|"queues offline"| node_local_db
node_sync_queue -->|"checks status"| node_network
node_sync_queue -->|"replays sales"| node_api_client
node_sync_queue -->|"reads and updates"| node_local_db
node_api_client -.->|"sends HTTP"| node_api_server
node_api_server -->|"configures routes"| node_router
node_api_server -->|"initializes database"| node_postgres
node_router -->|"routes login"| node_auth_handler
node_auth_handler -->|"delegates login"| node_auth_service
node_auth_service -->|"looks up user"| node_user_repo
node_router -->|"routes sales"| node_sale_handler
node_sale_handler -->|"delegates sale"| node_backend_sale_service
node_backend_sale_service -->|"persists sale"| node_sale_repo
node_router -->|"routes products"| node_products_handler
node_router -->|"routes validation"| node_terminal_handler
node_router -->|"routes reports"| node_report_handler
node_router -->|"constructs repository"| node_report_repo
node_report_handler -.->|"reads summaries"| node_report_repo

click node_app "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/pages/LoginPage.tsx"
click node_pos "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/pages/POSPage.tsx"
click node_products_ui "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/components/ProductGrid.tsx"
click node_cart_ui "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/components/CartTicket.tsx"
click node_payment_ui "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/components/PaymentModal.tsx"
click node_terminal "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useTerminalId.ts"
click node_auth_hook "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useAuth.ts"
click node_api_client "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/lib/api.ts"
click node_product_service "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/services/productService.ts"
click node_product_hook "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useProducts.ts"
click node_sale_service "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/services/saleService.ts"
click node_sync_queue "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useSyncQueue.ts"
click node_network "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useNetworkStatus.ts"
click node_local_db "https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/lib/db.ts"
click node_api_server "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/cmd/api/main.go"
click node_router "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/router/router.go"
click node_auth_handler "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/auth.go"
click node_auth_service "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/services/auth_service.go"
click node_user_repo "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/repositories/user_repository.go"
click node_sale_handler "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/sale.go"
click node_backend_sale_service "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/services/sale_service.go"
click node_sale_repo "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/repositories/sale_repository.go"
click node_products_handler "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/products.go"
click node_terminal_handler "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/terminal.go"
click node_report_handler "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/report.go"
click node_report_repo "https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/repositories/report_repository.go"

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,node_login,node_pos,node_products_ui,node_cart_ui,node_payment_ui,node_terminal,node_api_client toneBlue
class node_api_server,node_router,node_postgres toneAmber
class node_auth_hook,node_auth_handler,node_auth_service,node_user_repo toneMint
class node_sale_service,node_sync_queue,node_network,node_local_db,node_sale_handler,node_backend_sale_service,node_sale_repo toneRose
class node_product_service,node_product_hook,node_products_handler,node_terminal_handler,node_report_handler,node_report_repo,node_cashier toneIndigo
```

## Components

### POS frontend

- [App routing](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login page](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [POS page](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/pages/POSPage.tsx): `frontend/src/pages/POSPage.tsx`
- [Product grid](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/components/ProductGrid.tsx): `frontend/src/components/ProductGrid.tsx`
- [Cart ticket](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/components/CartTicket.tsx): `frontend/src/components/CartTicket.tsx`
- [Payment modal](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/components/PaymentModal.tsx): `frontend/src/components/PaymentModal.tsx`
- [Terminal setup](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useTerminalId.ts): `frontend/src/hooks/useTerminalId.ts`
- [HTTP client](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### POS API

- [API server](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/cmd/api/main.go): `backend/cmd/api/main.go`
- [HTTP routes](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/router/router.go): `backend/internal/router/router.go`

### Authentication

- [Session state](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Login handler](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/auth.go): `backend/internal/handlers/auth.go`
- [Auth service](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/services/auth_service.go): `backend/internal/services/auth_service.go`
- [User repository](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/repositories/user_repository.go): `backend/internal/repositories/user_repository.go`

### Sales and sync

- [Sale service](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/services/saleService.ts): `frontend/src/services/saleService.ts`
- [Sync queue](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useSyncQueue.ts): `frontend/src/hooks/useSyncQueue.ts`
- [Network status](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useNetworkStatus.ts): `frontend/src/hooks/useNetworkStatus.ts`
- [Local sales store](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/lib/db.ts): `frontend/src/lib/db.ts`
- [Sale handler](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/sale.go): `backend/internal/handlers/sale.go`
- [Sale service](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/services/sale_service.go): `backend/internal/services/sale_service.go`
- [Sale repository](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/repositories/sale_repository.go): `backend/internal/repositories/sale_repository.go`

### Catalog and reports

- [Product service](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/services/productService.ts): `frontend/src/services/productService.ts`
- [Product state](https://github.com/franciscogb03/tiendita-pos/blob/main/frontend/src/hooks/useProducts.ts): `frontend/src/hooks/useProducts.ts`
- [Products handler](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/products.go): `backend/internal/handlers/products.go`
- [Terminal handler](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/terminal.go): `backend/internal/handlers/terminal.go`
- [Report handler](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/handlers/report.go): `backend/internal/handlers/report.go`
- [Report repository](https://github.com/franciscogb03/tiendita-pos/blob/main/backend/internal/repositories/report_repository.go): `backend/internal/repositories/report_repository.go`

### Other components

- **Cashier**
- **PostgreSQL**

## Connections

- Cashier → App routing: uses (evidence: `frontend/src/App.tsx`)
- App routing → Login page: routes to (evidence: `frontend/src/App.tsx`)
- App routing → POS page: routes to (evidence: `frontend/src/App.tsx`)
- Login page → HTTP client: authenticates via (evidence: `frontend/src/pages/LoginPage.tsx`)
- POS page → Product grid: renders (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Cart ticket: renders (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Payment modal: renders (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Terminal setup: loads terminal (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Sale service: submits sale (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Sync queue: tracks sync (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Network status: reads status (evidence: `frontend/src/pages/POSPage.tsx`)
- POS page → Session state: reads session (evidence: `frontend/src/pages/POSPage.tsx`)
- Product grid → Product state: uses products
- Product state → Product service: loads products (evidence: `frontend/src/hooks/useProducts.ts`)
- Product service → HTTP client: requests products (evidence: `frontend/src/services/productService.ts`)
- Terminal setup → HTTP client: validates terminal (evidence: `frontend/src/hooks/useTerminalId.ts`)
- Sale service → HTTP client: posts sale (evidence: `frontend/src/services/saleService.ts`)
- Sale service → Local sales store: queues offline (evidence: `frontend/src/services/saleService.ts`)
- Sync queue → Network status: checks status (evidence: `frontend/src/hooks/useSyncQueue.ts`)
- Sync queue → HTTP client: replays sales (evidence: `frontend/src/hooks/useSyncQueue.ts`)
- Sync queue → Local sales store: reads and updates (evidence: `frontend/src/hooks/useSyncQueue.ts`)
- HTTP client → API server: sends HTTP
- API server → HTTP routes: configures routes (evidence: `backend/cmd/api/main.go`)
- API server → PostgreSQL: initializes database (evidence: `backend/cmd/api/main.go`)
- HTTP routes → Login handler: routes login (evidence: `backend/internal/router/router.go`)
- Login handler → Auth service: delegates login (evidence: `backend/internal/handlers/auth.go`)
- Auth service → User repository: looks up user (evidence: `backend/internal/services/auth_service.go`)
- HTTP routes → Sale handler: routes sales (evidence: `backend/internal/router/router.go`)
- Sale handler → Sale service: delegates sale (evidence: `backend/internal/handlers/sale.go`)
- Sale service → Sale repository: persists sale (evidence: `backend/internal/services/sale_service.go`)
- HTTP routes → Products handler: routes products (evidence: `backend/internal/router/router.go`)
- HTTP routes → Terminal handler: routes validation (evidence: `backend/internal/router/router.go`)
- HTTP routes → Report handler: routes reports (evidence: `backend/internal/router/router.go`)
- HTTP routes → Report repository: constructs repository (evidence: `backend/internal/router/router.go`)
- Report handler → Report repository: reads summaries