How gonzalo2324-dev/sistema-tpv-gesti-n-multi-tienda-saas- works
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.
Components 20
Clients
Three user-facing surfaces
- TPV · Checkout surface for physical stores
- Web Store · Customer-facing shopping surface
- Admin Panel · Business management surface
Backend
Central Node.js API
- Express API · Shared stateless HTTP backend for all clients
- Auth · Login, registration, JWT, and role control
- Device Reg · Registers TPV terminals and issues device UUIDs
- Catalog · Business-scoped product CRUD and browsing data
- Sales · Creates and lists sales records
- Stats · Reporting endpoints by device, store, and business scope
Domain
Multi-tenant retail model
- Business · SaaS tenant and top-level scope
- Store · Physical location within a business
- Device · Checkout terminal registered to a store
- User · Employees and admins scoped to a business
- Product · Business-scoped inventory item
- Sale · Operational sale record tied to business context
- Sale Detail · Per-item contents of a sale
- Inventory · Shared stock pool updated by all sales channels
Data
Persistence and local state
- MongoDB · System of record for tenants, catalog, and transactions
- Local UUID · Persisted terminal identifier on the TPV
Other components
- Retail SaaS · Multi-tenant retail platform for in-store and online commerce
Connections 27
- 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