# ph0void/asistente-de-ventas-pora-whatsapp-con-ia architecture

> Architecture diagram of the GitHub repository ph0void/asistente-de-ventas-pora-whatsapp-con-ia, 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/ph0void/asistente-de-ventas-pora-whatsapp-con-ia
- Repository: https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia

## Overview

#### Purpose
This repository is intended to run a 24/7 WhatsApp sales assistant. It responds to customer messages, presents/searches a product catalog, records customers and orders, and writes invoices and operational data to Google Sheets.

#### Available Repository Surface
Only `README.md` is present in the supplied tree. The README describes intended behavior and startup commands, but no application source, package manifest, environment template, or deployment files are available to verify implementation details.

#### Entry Point and Startup Model
The documented operator flow is:
1. Install Node.js dependencies with `npm install`.
2. Configure a Google Sheet ID in `.env`.
3. Launch development mode with `npm run dev`.
4. Scan a WhatsApp QR code to authorize the bot session.

The implied runtime entry point is an npm development script, but its target cannot be identified without `package.json`.

#### WhatsApp Interaction Boundary
The bot’s external conversational boundary is WhatsApp Web, described as using `whatsapp-web.js`. Incoming customer messages should drive the sales workflow; outbound messages provide conversational replies, catalog information, and simulated typing behavior. QR authorization and persistent session storage are required for account access continuity.

Grounding: `README.md`.

#### AI Response and Decision Stage
An AI provider interprets customer context and generates natural-language sales responses. The README names Ollama, GPT-4, and Gemini as selectable model backends, implying a provider abstraction or configurable inference boundary. No prompt logic, model-selection mechanism, credentials handling, or fallback behavior is visible.

Grounding: `README.md`.

#### Commerce Workflow Stage
The stated business capabilities form the core domain flow: identify/register a customer, search or share catalog items, create an order, retain conversation history, and create invoice records. Google Sheets is positioned as the operational system of record rather than merely an export target.

Grounding: `README.md`.

#### Persistence and External Services
Material external dependencies are:
- WhatsApp Web / `whatsapp-web.js` for messaging and account sessions.
- Google Sheets for customers, products, orders, and invoices.
- One of Ollama, OpenAI GPT-4, or Google Gemini for AI responses.
- Local persistent storage for WhatsApp authentication/session state.

Credentials and sheet identifiers are implied to be environment-driven through `.env`, but no actual configuration contract is included.

Grounding: `README.md`.

#### Architectural Gaps
The supplied repository cannot establish module boundaries, data schemas, webhook/polling behavior, concurrency controls, error recovery, Google authentication method, or production hosting topology. Before extending or graph-planning the implementation, recover the missing source tree and especially `package.json`, environment documentation, WhatsApp session storage setup, and Sheets integration code.

Main entry points: [`README.md`](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md) (WhatsApp Sales Assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_npm_dev["npm run dev<br/>startup command<br/>[README.md]"]
  node_sales_assistant["WhatsApp Sales Assistant<br/>Node.js bot<br/>[README.md]"]
  node_sales_workflow["Sales Workflow<br/>commerce orchestration<br/>[README.md]"]
end

subgraph group_external["External Services"]
  node_whatsapp{{"WhatsApp Web<br/>messaging platform<br/>[README.md]"}}
  node_ai_provider{{"AI Provider<br/>[README.md]"}}
  node_google_sheets[("Google Sheets<br/>operational system of record<br/>[README.md]")]
end

subgraph group_data["Operational Data"]
  node_session_store[("Session Storage<br/>local auth state<br/>[README.md]")]
  node_customers[("Customers<br/>sheet records<br/>[README.md]")]
  node_products[("Product Catalog<br/>sheet records<br/>[README.md]")]
  node_orders[("Orders<br/>sheet records<br/>[README.md]")]
  node_invoices["Invoices<br/>sheet records<br/>[README.md]"]
  node_conversation_history[("Conversation History<br/>customer context<br/>[README.md]")]
end

node_operator(("Operator<br/>user<br/>[README.md]"))
node_customer(("Customer Messages<br/>conversation input<br/>[README.md]"))

node_operator -->|"starts"| node_npm_dev
node_npm_dev -->|"launches"| node_sales_assistant
node_sales_assistant -->|"connects via whatsapp-web.js"| node_whatsapp
node_whatsapp -->|"delivers messages"| node_sales_assistant
node_sales_assistant -->|"persists auth session"| node_session_store
node_customer -->|"sends message"| node_whatsapp
node_sales_assistant -->|"routes conversation"| node_sales_workflow
node_sales_workflow -->|"requests sales response"| node_ai_provider
node_ai_provider -->|"generated reply"| node_sales_assistant
node_sales_workflow -->|"reads and writes records"| node_google_sheets
node_google_sheets -->|"stores"| node_customers
node_google_sheets -->|"stores"| node_products
node_google_sheets -->|"stores"| node_orders
node_google_sheets -->|"stores"| node_invoices
node_sales_workflow -->|"retains context"| node_conversation_history
node_sales_assistant -->|"sends replies and catalog"| node_whatsapp

click node_operator "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_npm_dev "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_sales_assistant "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_session_store "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_whatsapp "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_customer "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_ai_provider "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_sales_workflow "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_google_sheets "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_customers "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_products "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_orders "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_invoices "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"
click node_conversation_history "https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md"

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_npm_dev,node_sales_assistant,node_sales_workflow toneBlue
class node_whatsapp,node_ai_provider,node_google_sheets toneAmber
class node_session_store,node_customers,node_products,node_orders,node_invoices,node_conversation_history toneMint
class node_operator,node_customer toneNeutral
```

## Components

### Bot Runtime

Implementation boundaries are inferred from README.

- [npm run dev](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): startup command · Documented development launch entry; script target is unknown. · `README.md`
- [WhatsApp Sales Assistant](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): Node.js bot · Core implementation is not present in the supplied repository. · `README.md`
- [Sales Workflow](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): commerce orchestration · Identifies customers, searches catalog, creates orders, and retains history. · `README.md`

### External Services

- [WhatsApp Web](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): messaging platform · `README.md`
- [AI Provider](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): Ollama / GPT-4 / Gemini · Interprets customer context and generates sales replies. · `README.md`
- [Google Sheets](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): operational system of record · Stores operational commerce records. · `README.md`

### Operational Data

- [Session Storage](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): local auth state · Persists WhatsApp authorization state. · `README.md`
- [Customers](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): sheet records · `README.md`
- [Product Catalog](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): sheet records · `README.md`
- [Orders](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): sheet records · `README.md`
- [Invoices](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): sheet records · `README.md`
- [Conversation History](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): customer context · `README.md`

### Other components

- [Operator](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): user · `README.md`
- [Customer Messages](https://github.com/ph0void/asistente-de-ventas-pora-whatsapp-con-ia/blob/main/README.md): conversation input · `README.md`

## Connections

- Operator → npm run dev: starts
- npm run dev → WhatsApp Sales Assistant: launches
- WhatsApp Sales Assistant → WhatsApp Web: connects via whatsapp-web.js
- WhatsApp Web → WhatsApp Sales Assistant: delivers messages
- WhatsApp Sales Assistant → Session Storage: persists auth session
- Customer Messages → WhatsApp Web: sends message
- WhatsApp Sales Assistant → Sales Workflow: routes conversation
- Sales Workflow → AI Provider: requests sales response
- AI Provider → WhatsApp Sales Assistant: generated reply
- Sales Workflow → Google Sheets: reads and writes records
- Google Sheets → Customers: stores
- Google Sheets → Product Catalog: stores
- Google Sheets → Orders: stores
- Google Sheets → Invoices: stores
- Sales Workflow → Conversation History: retains context
- WhatsApp Sales Assistant → WhatsApp Web: sends replies and catalog