# alessandr0gabriel/vendly-commerce architecture

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

- Interactive diagram: https://gitdiagram.com/alessandr0gabriel/vendly-commerce
- Repository: https://github.com/alessandr0gabriel/vendly-commerce

## Overview

Vendly Commerce is a multi-tenant commerce-management SaaS for small establishments. Establishment staff sign in, manage products and stock, handle orders, and review sales and billing; administrators also manage establishments and subscriptions. The browser modules call the Express API, which applies business rules and persists data through Firebase/Firestore, while Socket.IO supports real-time order updates. The README documents payments, webhooks, and subscriptions; some detailed routes and their wiring were not sampled, so those links are shown only where documented or directly evidenced.

Main entry points: [`frontend/js/admin.js`](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/admin.js) (Admin interface), [`backend/api.js`](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/api.js) (Business API), [`backend/server.js`](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/server.js) (HTTP and socket server), [`frontend/js/core/api.js`](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/api.js) (Authenticated API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser application"]
  node_adminui["Admin interface<br/>[admin.js]"]
  node_auth["Session verification<br/>[auth.js]"]
  node_products["Products and stock<br/>[produtos.js]"]
  node_orders["Order management<br/>[pedidos.js]"]
  node_dashboard["Sales dashboard<br/>[dashboardFull.js]"]
  node_billing["Billing reports<br/>[faturamento.js]"]
  node_establishment["Establishment settings<br/>[estabelecimento.js]"]
  node_browserapi["Authenticated API client<br/>[api.js]"]
  node_socketclient["Live order client<br/>[socket.js]"]
end

subgraph group_service["API and business operations"]
  node_server["HTTP and socket server<br/>[server.js]"]
  node_api["Business API<br/>[api.js]"]
  node_authrest["Firebase sign-in"]
  node_subscription["Subscription rules<br/>[assinatura.js]"]
  node_pricing["Subscription pricing"]
  node_stockrules["Stock reservation rules<br/>[reservaEstoque.js]"]
  node_historyjob["Order history cleanup"]
  node_pixjob["Expired PIX cleanup"]
end

subgraph group_platform["Persistence and integrations"]
  node_connection["Database initialization<br/>[connection.js]"]
  node_firebase["Firebase services<br/>[firebase.js]"]
  node_firestore[("Firestore data")]
end

node_staff(("Establishment staff"))
node_mp["Mercado Pago"]

node_staff -->|"uses"| node_adminui
node_adminui -->|"checks session"| node_auth
node_adminui -->|"loads"| node_products
node_adminui -->|"loads"| node_orders
node_adminui -->|"loads"| node_billing
node_adminui -->|"loads"| node_establishment
node_auth -->|"checks token"| node_browserapi
node_auth -->|"starts socket"| node_socketclient
node_products -->|"requests data"| node_browserapi
node_orders -->|"requests data"| node_browserapi
node_dashboard -->|"requests data"| node_browserapi
node_billing -->|"requests data"| node_browserapi
node_browserapi -->|"sends requests"| node_server
node_socketclient -->|"connects live"| node_server
node_server -->|"awaits connection"| node_connection
node_server -->|"starts cleanup"| node_historyjob
node_server -->|"starts cleanup"| node_pixjob
node_server -->|"mounts routes"| node_api
node_connection -->|"loads services"| node_firebase
node_connection -->|"seeds admin"| node_firestore
node_api -->|"reads and writes"| node_firestore
node_api -->|"uses rules"| node_stockrules
node_api -->|"uses rules"| node_subscription
node_pricing -->|"uses calculations"| node_subscription
node_api -->|"processes payments"| node_mp
node_api -.->|"signs in"| node_authrest

click node_adminui "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/admin.js"
click node_auth "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/auth.js"
click node_products "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/produtos.js"
click node_orders "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/pedidos.js"
click node_dashboard "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/dashboardFull.js"
click node_billing "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/faturamento.js"
click node_establishment "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/estabelecimento.js"
click node_browserapi "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/api.js"
click node_socketclient "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/socket.js"
click node_server "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/server.js"
click node_api "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/api.js"
click node_authrest "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/firebaseAuthRest.js"
click node_subscription "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/assinatura.js"
click node_pricing "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/precosAssinatura.js"
click node_stockrules "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/reservaEstoque.js"
click node_historyjob "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/jobs/historicoArquivar.js"
click node_pixjob "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/jobs/limparPixExpirados.js"
click node_connection "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/database/connection.js"
click node_firebase "https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/config/firebase.js"

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_adminui,node_auth,node_products,node_orders,node_dashboard,node_billing,node_establishment,node_browserapi,node_socketclient toneBlue
class node_server,node_api,node_authrest,node_subscription,node_pricing,node_stockrules,node_historyjob,node_pixjob toneAmber
class node_connection,node_firebase,node_firestore toneMint
class node_staff,node_mp toneIndigo
```

## Components

### Browser application

- [Admin interface](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/admin.js): `frontend/js/admin.js`
- [Session verification](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/auth.js): `frontend/js/core/auth.js`
- [Products and stock](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/produtos.js): `frontend/js/modules/produtos.js`
- [Order management](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/pedidos.js): `frontend/js/modules/pedidos.js`
- [Sales dashboard](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/dashboardFull.js): `frontend/js/modules/dashboardFull.js`
- [Billing reports](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/faturamento.js): `frontend/js/modules/faturamento.js`
- [Establishment settings](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/modules/estabelecimento.js): `frontend/js/modules/estabelecimento.js`
- [Authenticated API client](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/api.js): `frontend/js/core/api.js`
- [Live order client](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/frontend/js/core/socket.js): `frontend/js/core/socket.js`

### API and business operations

- [HTTP and socket server](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/server.js): `backend/server.js`
- [Business API](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/api.js): `backend/api.js`
- [Firebase sign-in](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/firebaseAuthRest.js): `backend/utils/firebaseAuthRest.js`
- [Subscription rules](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/assinatura.js): `backend/utils/assinatura.js`
- [Subscription pricing](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/precosAssinatura.js): `backend/utils/precosAssinatura.js`
- [Stock reservation rules](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/utils/reservaEstoque.js): `backend/utils/reservaEstoque.js`
- [Order history cleanup](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/jobs/historicoArquivar.js): `backend/jobs/historicoArquivar.js`
- [Expired PIX cleanup](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/jobs/limparPixExpirados.js): `backend/jobs/limparPixExpirados.js`

### Persistence and integrations

- [Database initialization](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/database/connection.js): `backend/database/connection.js`
- [Firebase services](https://github.com/alessandr0gabriel/vendly-commerce/blob/main/backend/config/firebase.js): `backend/config/firebase.js`
- **Firestore data**

### Other components

- **Establishment staff**
- **Mercado Pago**

## Connections

- Establishment staff → Admin interface: uses (evidence: `README.md`)
- Admin interface → Session verification: checks session (evidence: `frontend/js/admin.js`)
- Admin interface → Products and stock: loads (evidence: `frontend/js/admin.js`)
- Admin interface → Order management: loads (evidence: `frontend/js/admin.js`)
- Admin interface → Billing reports: loads (evidence: `frontend/js/admin.js`)
- Admin interface → Establishment settings: loads (evidence: `frontend/js/admin.js`)
- Session verification → Authenticated API client: checks token (evidence: `frontend/js/core/auth.js`)
- Session verification → Live order client: starts socket (evidence: `frontend/js/core/auth.js`)
- Products and stock → Authenticated API client: requests data (evidence: `frontend/js/modules/produtos.js`)
- Order management → Authenticated API client: requests data (evidence: `frontend/js/modules/pedidos.js`)
- Sales dashboard → Authenticated API client: requests data (evidence: `frontend/js/modules/dashboardFull.js`)
- Billing reports → Authenticated API client: requests data (evidence: `frontend/js/modules/faturamento.js`)
- Authenticated API client → HTTP and socket server: sends requests (evidence: `README.md`)
- Live order client → HTTP and socket server: connects live (evidence: `README.md`)
- HTTP and socket server → Database initialization: awaits connection (evidence: `backend/server.js`)
- HTTP and socket server → Order history cleanup: starts cleanup (evidence: `backend/server.js`)
- HTTP and socket server → Expired PIX cleanup: starts cleanup (evidence: `backend/server.js`)
- HTTP and socket server → Business API: mounts routes (evidence: `backend/server.js`)
- Database initialization → Firebase services: loads services (evidence: `backend/database/connection.js`)
- Database initialization → Firestore data: seeds admin (evidence: `backend/database/connection.js`)
- Business API → Firestore data: reads and writes (evidence: `backend/api.js`)
- Business API → Stock reservation rules: uses rules (evidence: `backend/api.js`)
- Business API → Subscription rules: uses rules (evidence: `backend/api.js`)
- Subscription pricing → Subscription rules: uses calculations (evidence: `backend/utils/precosAssinatura.js`)
- Business API → Mercado Pago: processes payments (evidence: `README.md`)
- Business API → Firebase sign-in: signs in (evidence: `backend/api.js`)