# forgemind-git/forgegrowth-oss architecture

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

- Interactive diagram: https://gitdiagram.com/forgemind-git/forgegrowth-oss
- Repository: https://github.com/forgemind-git/forgegrowth-oss

## Overview

Forge Growth is a self-hosted WhatsApp-centered CRM that connects Meta ad referrals to conversations, leads, funnel stages, and attributed payments. The principal flow is inbound WhatsApp webhook processing, lead and click-referral capture, automation or agent response, sales-stage tracking, and payment reconciliation. The frontend provides workspace views through an API client; backend routes, engines, services, queues, and integrations implement the domain behavior. Several capabilities are README-documented but their implementation was not sampled, so those links are documented relationships rather than inferred calls.

Main entry points: [`backend/src/routes/webhook.js`](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/webhook.js) (WhatsApp webhook), [`backend/src/engine/agentEngine.js`](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/engine/agentEngine.js) (Agent engine), [`backend/src/routes/leads.js`](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/leads.js) (Lead management), [`frontend/src/api.js`](https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Workspace shell<br/>[App.jsx]"]
  node_client["API client<br/>[api.js]"]
  node_pipeline_ui["Lead pipeline view<br/>[PipelinePage.jsx]"]
  node_campaign_ui["Campaign workspace<br/>[CampaignsPage.jsx]"]
end

subgraph group_messaging["Messaging and automation"]
  node_webhook["WhatsApp webhook<br/>[webhook.js]"]
  node_automation["Automation engine"]
  node_agent["Agent engine<br/>[agentEngine.js]"]
  node_agent_queue["Agent queue<br/>[agentQueue.js]"]
  node_send_queue["Send queue<br/>[sendQueue.js]"]
  node_sender["Message sender<br/>[messageSender.js]"]
end

subgraph group_sales["Growth and sales"]
  node_lead_routes["Lead management<br/>[leads.js]"]
  node_ctwa["Click referrals<br/>[ctwa.js]"]
  node_funnel["Funnel configuration<br/>[funnelConfig.js]"]
  node_campaigns["Campaign analytics<br/>[marketing.js]"]
  node_payments["Payment requests<br/>[paymentRequests.js]"]
end

subgraph group_platform["Backend platform"]
  node_db[("Postgres data<br/>[db.js]")]
  node_events["Live event bus<br/>[events.js]"]
  node_media["Media library<br/>[mediaLibrary.js]"]
  node_object_store[("Media object store<br/>[minioClient.js]")]
end

node_operator(("Operator"))
node_whatsapp(("WhatsApp platform"))
node_razorpay(("Razorpay"))
node_meta_ads(("Meta Marketing API"))

node_operator -->|"uses"| node_app
node_app -->|"requests"| node_client
node_pipeline_ui -->|"loads leads"| node_client
node_campaign_ui -.->|"loads campaigns"| node_client
node_client -.->|"HTTP requests"| node_lead_routes
node_whatsapp -.->|"sends events"| node_webhook
node_webhook -->|"dispatches"| node_automation
node_webhook -->|"routes agents"| node_agent
node_webhook -->|"records referral"| node_ctwa
node_webhook -->|"resolves leads"| node_lead_routes
node_agent_queue -.->|"runs"| node_agent
node_agent -->|"enqueues replies"| node_send_queue
node_automation -->|"enqueues messages"| node_send_queue
node_send_queue -->|"delegates sends"| node_sender
node_sender -.->|"sends messages"| node_whatsapp
node_lead_routes -->|"uses funnel rules"| node_funnel
node_lead_routes -->|"emits updates"| node_events
node_campaigns -.->|"fetches spend"| node_meta_ads
node_campaigns -.->|"joins click attribution"| node_ctwa
node_payments -.->|"creates payment links"| node_razorpay
node_razorpay -.->|"reports payments"| node_payments
node_automation -->|"reads and writes"| node_db
node_agent -->|"reads and writes"| node_db
node_webhook -->|"stores events"| node_db
node_media -->|"stores media"| node_object_store

click node_app "https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/App.jsx"
click node_client "https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/api.js"
click node_pipeline_ui "https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/pages/sales/PipelinePage.jsx"
click node_campaign_ui "https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/pages/marketing/CampaignsPage.jsx"
click node_webhook "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/webhook.js"
click node_automation "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/engine/automationEngine.js"
click node_agent "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/engine/agentEngine.js"
click node_agent_queue "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/queue/agentQueue.js"
click node_send_queue "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/queue/sendQueue.js"
click node_sender "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/services/messageSender.js"
click node_lead_routes "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/leads.js"
click node_ctwa "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/ctwa.js"
click node_funnel "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/services/funnelConfig.js"
click node_campaigns "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/marketing.js"
click node_payments "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/paymentRequests.js"
click node_db "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/db.js"
click node_events "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/events.js"
click node_media "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/mediaLibrary.js"
click node_object_store "https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/util/minioClient.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_app,node_client,node_pipeline_ui,node_campaign_ui toneBlue
class node_webhook,node_automation,node_agent,node_agent_queue,node_send_queue,node_sender toneAmber
class node_lead_routes,node_ctwa,node_funnel,node_campaigns,node_payments,node_meta_ads toneMint
class node_db,node_events,node_media,node_object_store toneRose
class node_operator,node_whatsapp,node_razorpay toneIndigo
```

## Components

### User experience

- [Workspace shell](https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Lead pipeline view](https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/pages/sales/PipelinePage.jsx): `frontend/src/pages/sales/PipelinePage.jsx`
- [Campaign workspace](https://github.com/forgemind-git/forgegrowth-oss/blob/main/frontend/src/pages/marketing/CampaignsPage.jsx): `frontend/src/pages/marketing/CampaignsPage.jsx`

### Messaging and automation

- [WhatsApp webhook](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/webhook.js): `backend/src/routes/webhook.js`
- [Automation engine](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/engine/automationEngine.js): `backend/src/engine/automationEngine.js`
- [Agent engine](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/engine/agentEngine.js): `backend/src/engine/agentEngine.js`
- [Agent queue](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/queue/agentQueue.js): `backend/src/queue/agentQueue.js`
- [Send queue](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/queue/sendQueue.js): `backend/src/queue/sendQueue.js`
- [Message sender](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/services/messageSender.js): `backend/src/services/messageSender.js`

### Growth and sales

- [Lead management](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/leads.js): `backend/src/routes/leads.js`
- [Click referrals](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/ctwa.js): `backend/src/routes/ctwa.js`
- [Funnel configuration](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/services/funnelConfig.js): `backend/src/services/funnelConfig.js`
- [Campaign analytics](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/marketing.js): `backend/src/routes/marketing.js`
- [Payment requests](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/paymentRequests.js): `backend/src/routes/paymentRequests.js`

### Backend platform

- [Postgres data](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/db.js): `backend/src/db.js`
- [Live event bus](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/events.js): `backend/src/events.js`
- [Media library](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/routes/mediaLibrary.js): `backend/src/routes/mediaLibrary.js`
- [Media object store](https://github.com/forgemind-git/forgegrowth-oss/blob/main/backend/src/util/minioClient.js): `backend/src/util/minioClient.js`

### Other components

- **Operator**
- **WhatsApp platform**
- **Razorpay**
- **Meta Marketing API**

## Connections

- Operator → Workspace shell: uses (evidence: `frontend/src/App.jsx`)
- Workspace shell → API client: requests (evidence: `frontend/src/App.jsx`)
- Lead pipeline view → API client: loads leads (evidence: `frontend/src/pages/sales/PipelinePage.jsx`)
- Campaign workspace → API client: loads campaigns
- API client → Lead management: HTTP requests
- WhatsApp platform → WhatsApp webhook: sends events
- WhatsApp webhook → Automation engine: dispatches (evidence: `backend/src/routes/webhook.js`)
- WhatsApp webhook → Agent engine: routes agents (evidence: `backend/src/routes/webhook.js`)
- WhatsApp webhook → Click referrals: records referral (evidence: `backend/src/routes/webhook.js`)
- WhatsApp webhook → Lead management: resolves leads (evidence: `backend/src/routes/webhook.js`)
- Agent queue → Agent engine: runs
- Agent engine → Send queue: enqueues replies (evidence: `backend/src/engine/agentEngine.js`)
- Automation engine → Send queue: enqueues messages (evidence: `backend/src/engine/automationEngine.js`)
- Send queue → Message sender: delegates sends (evidence: `backend/src/queue/sendQueue.js`)
- Message sender → WhatsApp platform: sends messages
- Lead management → Funnel configuration: uses funnel rules (evidence: `backend/src/routes/leads.js`)
- Lead management → Live event bus: emits updates (evidence: `backend/src/routes/leads.js`)
- Campaign analytics → Meta Marketing API: fetches spend (evidence: `README.md`)
- Campaign analytics → Click referrals: joins click attribution (evidence: `README.md`)
- Payment requests → Razorpay: creates payment links (evidence: `README.md`)
- Razorpay → Payment requests: reports payments (evidence: `README.md`)
- Automation engine → Postgres data: reads and writes (evidence: `backend/src/engine/automationEngine.js`)
- Agent engine → Postgres data: reads and writes (evidence: `backend/src/engine/agentEngine.js`)
- WhatsApp webhook → Postgres data: stores events (evidence: `backend/src/routes/webhook.js`)
- Media library → Media object store: stores media (evidence: `backend/src/routes/mediaLibrary.js`)
