# gonzalo2324-dev/sistema-tpv-gesti-n-multi-tienda-saas- architecture

> Architecture diagram of the GitHub repository gonzalo2324-dev/sistema-tpv-gesti-n-multi-tienda-saas-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gonzalo2324-dev/sistema-tpv-gesti-n-multi-tienda-saas-
- Repository: https://github.com/gonzalo2324-dev/sistema-tpv-gesti-n-multi-tienda-saas-

## Overview

1. **Repository purpose**
   - This repo describes a **multi-tenant retail SaaS platform** for physical and online stores.
   - The system is centered on a shared backend that serves three client surfaces: **TPV**, **customer web store**, and **admin panel**.

2. **Top-level architecture**
   - The main shape is a **client-server model**:
     - **TPV (Electron or web app)** for in-store checkout
     - **Web store** for customers
     - **Admin panel** for business operators
     - All of them communicate with a central **Node.js/Express API**
     - The API persists data in **MongoDB**

3. **Core backend boundary**
   - The backend is the system of record.
   - It owns authentication, tenant isolation, business/store/device data, product catalog, sales persistence, and inventory updates.
   - This is the main integration point for every frontend.

4. **Multi-tenant domain model**
   - The architecture is organized around these main entities:
     - **Business**: the SaaS tenant / client company
     - **Store**: physical locations within a business
     - **Device**: individual checkout terminals registered to a store
     - **User**: employees and admins scoped to a business
     - **Product**: catalog items scoped to a business
     - **Sale** and **SaleDetail**: transactional records tied to business, store, device, and user
   - Diagrammatically, **Business** sits above Stores, Users, Products, and operational data.

5. **TPV flow**
   - The TPV is the operational checkout client.
   - On first run it performs **device registration** using business ID, user credentials, and device name.
   - The device gets a **UUID** stored locally and reused on subsequent requests.
   - During checkout, the TPV sends sale data to the backend, which records the sale and updates stock.

6. **Customer web flow**
   - The customer-facing web app reads product data from the same backend.
   - It supports browsing, cart, login/registration, and online purchases.
   - Online sales affect the same inventory pool, so stock is shared across physical and digital channels.

7. **Admin panel flow**
   - The admin panel is the management surface for the business.
   - It is used for product management, employee management, configuration, and reporting.
   - It consumes the backend’s statistics endpoints to show metrics by **device**, **store**, and **business-wide** scope.

8. **Operational data flow**
   - The main cross-cutting flow is **inventory synchronization**:
     - TPV sale → backend sale record → stock decrement
     - Web purchase → backend sale record → stock decrement
   - This makes the backend the single source of truth for stock levels across all channels.

9. **Authentication and authorization**
   - Security is based on **hashed passwords**, **JWT authentication**, and **role control**.
   - Roles are explicitly split into **admin** and **employee**.
   - Access decisions are likely enforced at the API boundary, with business scoping applied to all major resources.

10. **API surface**
    - The documented API groups are:
      - **Auth**: login and registration
      - **Businesses**: tenant management
      - **Stores**: location management
      - **Devices**: device registration and listing
      - **Products**: catalog CRUD
      - **Sales**: sale creation, listing, and stats
    - These endpoints are the integration contract for all clients.

11. **Persistence layer**
    - The only named datastore is **MongoDB**.
    - The data model suggests separate collections for businesses, stores, devices, users, products, sales, and sale details.
    - Sales appear to be the transactional record that links operational context to inventory changes.

12. **Deployment/runtime implications**
    - The backend is explicitly **Node.js + Express**, so the server side is a stateless HTTP API.
    - The TPV may be packaged as **Electron** or run as a web app, which matters because it needs local UUID persistence and full-screen kiosk behavior.
    - The overall architecture is designed to support SaaS expansion rather than a single-store installation.

13. **What is not present yet**
    - The repo currently contains only the README, so there is no concrete implementation tree to infer component boundaries beyond the documented architecture.
    - For a diagram, treat the README as the authoritative source for intended system structure, not as evidence of implemented modules.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_tpv["TPV<br/>client app"]
  node_webstore["Web Store<br/>client app"]
  node_admin["Admin Panel<br/>client app"]
end

subgraph group_backend["Backend"]
  node_api["Express API<br/>server"]
  node_auth(("Auth<br/>api boundary"))
  node_devicesvc(("Device Reg<br/>api flow"))
  node_catalogsvc(("Catalog<br/>api flow"))
  node_salessvc(("Sales<br/>api flow"))
  node_statssvc(("Stats<br/>api flow"))
end

subgraph group_domain["Domain"]
  node_business[("Business<br/>tenant")]
  node_store[("Store<br/>location")]
  node_device[("Device<br/>terminal")]
  node_user[("User<br/>identity")]
  node_product[("Product<br/>catalog item")]
  node_sale[("Sale<br/>transaction")]
  node_saledetail[("Sale Detail<br/>line item")]
  node_inventory[("Inventory<br/>stock state")]
end

subgraph group_data["Data"]
  node_mongo[("MongoDB<br/>datastore")]
  node_localuuid["Local UUID<br/>device state"]
end

node_platform{{"Retail SaaS"}}

node_platform -->|"includes"| node_tpv
node_platform -->|"includes"| node_webstore
node_platform -->|"includes"| node_admin
node_tpv -->|"calls"| node_api
node_webstore -->|"calls"| node_api
node_admin -->|"calls"| node_api
node_api -->|"enforces"| node_auth
node_api -->|"serves"| node_devicesvc
node_api -->|"serves"| node_catalogsvc
node_api -->|"serves"| node_salessvc
node_api -->|"serves"| node_statssvc
node_auth -->|"authenticates"| node_user
node_devicesvc -->|"creates"| node_device
node_devicesvc -->|"issues"| node_localuuid
node_business -->|"owns"| node_store
node_business -->|"scopes"| node_user
node_business -->|"scopes"| node_product
node_business -->|"records"| node_sale
node_store -->|"contains"| node_device
node_sale -->|"has"| node_saledetail
node_sale -->|"decrements"| node_inventory
node_product -->|"feeds"| node_inventory
node_salessvc -->|"persists"| node_sale
node_catalogsvc -->|"reads-writes"| node_product
node_statssvc -->|"aggregates"| node_sale
node_api -->|"stores"| node_mongo
node_localuuid -->|"identifies"| node_device

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_tpv,node_webstore,node_admin toneBlue
class node_api,node_auth,node_devicesvc,node_catalogsvc,node_salessvc,node_statssvc toneAmber
class node_business,node_store,node_device,node_user,node_product,node_sale,node_saledetail,node_inventory toneMint
class node_mongo,node_localuuid toneRose
class node_platform toneNeutral
```

## Components

### Clients

Three user-facing surfaces

- **TPV**: client app · Checkout surface for physical stores
- **Web Store**: client app · Customer-facing shopping surface
- **Admin Panel**: client app · Business management surface

### Backend

Central Node.js API

- **Express API**: server · Shared stateless HTTP backend for all clients
- **Auth**: api boundary · Login, registration, JWT, and role control
- **Device Reg**: api flow · Registers TPV terminals and issues device UUIDs
- **Catalog**: api flow · Business-scoped product CRUD and browsing data
- **Sales**: api flow · Creates and lists sales records
- **Stats**: api flow · Reporting endpoints by device, store, and business scope

### Domain

Multi-tenant retail model

- **Business**: tenant · SaaS tenant and top-level scope
- **Store**: location · Physical location within a business
- **Device**: terminal · Checkout terminal registered to a store
- **User**: identity · Employees and admins scoped to a business
- **Product**: catalog item · Business-scoped inventory item
- **Sale**: transaction · Operational sale record tied to business context
- **Sale Detail**: line item · Per-item contents of a sale
- **Inventory**: stock state · Shared stock pool updated by all sales channels

### Data

Persistence and local state

- **MongoDB**: datastore · System of record for tenants, catalog, and transactions
- **Local UUID**: device state · Persisted terminal identifier on the TPV

### Other components

- **Retail SaaS**: system · Multi-tenant retail platform for in-store and online commerce

## Connections

- Retail SaaS → TPV: includes · Platform exposes operational checkout
- Retail SaaS → Web Store: includes · Platform exposes customer shopping
- Retail SaaS → Admin Panel: includes · Platform exposes management tools
- TPV → Express API: calls · Checkout operations are sent to the shared backend
- Web Store → Express API: calls · Browse and purchase requests hit the backend
- Admin Panel → Express API: calls · Admin actions and reporting use API endpoints
- Express API → Auth: enforces · Authentication and role checks happen at the API boundary
- Express API → Device Reg: serves · Device registration and listing
- Express API → Catalog: serves · Product CRUD and catalog reads
- Express API → Sales: serves · Sale creation, listing, and stats inputs
- Express API → Stats: serves · Business, store, and device metrics
- Auth → User: authenticates · Uses stored user identity and roles
- Device Reg → Device: creates · Registers terminals as device records
- Device Reg → Local UUID: issues · TPV stores UUID locally after first registration
- Business → Store: owns · A tenant contains multiple stores
- Business → User: scopes · Employees and admins belong to a business
- Business → Product: scopes · Catalog is tenant-specific
- Business → Sale: records · Sales are tracked per tenant
- Store → Device: contains · Devices are registered to a store
- Sale → Sale Detail: has · Sales contain line items
- Sale → Inventory: decrements · Every sale reduces stock
- Product → Inventory: feeds · Products are the stocked catalog entries
- Sales → Sale: persists · Sale data is written as transactional records
- Catalog → Product: reads-writes · Catalog operations target product records
- Stats → Sale: aggregates · Reporting reads sales data
- Express API → MongoDB: stores · Central persistence for all major entities
- Local UUID → Device: identifies · Terminal UUID ties requests to a registered device
