GrowthOS

Live: https://growos-ai.vercel.app — open the demo with no sign-up. When the AWS backend is switched on, upload your own CSV and the agent runs in ~60 seconds. See DEPLOYMENT.md for how the always-on demo and the on-demand backend fit together.

---

What It Does

Traditional CRMs make the marketer do all the thinking: build a segment, write a message, pick a channel, schedule a send. GrowthOS inverts this.

A scheduled growth agent prepares the work while the marketer keeps execution control:

1. Ingests your customer + order history (CSV upload)
2. Computes RFM behavioural segments, purchase patterns, and category preferences
3. Assigns AI-generated personas to each customer cluster
4. Surfaces revenue opportunities: "76 dormant VIPs haven't bought in 90 days — ₹1.1L recoverable"
5. Generates campaign copy, audience definition, recommended channel, and predicted revenue
6. Pauses durably for a marketer to review, refine, approve, and launch

The marketer's job shifts from building to steering.

---

Architecture

Three independently deployable services:

┌─────────────────────────────────────────────────────────────┐
│  Frontend — Next.js App Router (Vercel)                     │
│  Onboarding · Dashboard · Opportunities · Campaigns · Analytics │
└────────────────────────┬────────────────────────────────────┘
                         │ REST + Auth JWT
┌────────────────────────▼────────────────────────────────────┐
│  Backend API — Express.js (Render)                          │
│  Ingestion · RFM Engine · AI Orchestrator · Campaign API     │
│  requireAuth + resolveCompanyMiddleware on every route       │
└──────────┬──────────────────────────────┬───────────────────┘
           │                              │ PostgreSQL + RLS
┌──────────▼──────────┐     ┌─────────────▼───────────────────┐
│ BullMQ Worker       │────▶│  Channel Service                 │
│ Recipient outbox    │     │  Twilio / Resend / Simulator    │
└──────────┬──────────┘     └─────────────┬───────────────────┘
           │ Redis                         │ HMAC callbacks
           └───────────────────────────────┘

graph TD
    subgraph CLIENT["Frontend — Next.js (Vercel)"]
        ONB[Onboarding Wizard]
        OPP[Opportunities Page]
        CAM[Campaigns Page]
        ANA[Analytics Page]
    end

    subgraph BACKEND["Backend API — Express.js (Render)"]
        ING[Data Ingestion + RFM Engine]
        PER[AI Persona Engine]
        OPP_SVC[AI Opportunity Engine]
        CAM_SVC[AI Campaign Generator]
        LAUNCH[Campaign Launcher]
        WH[Webhook Receiver]
    end

    subgraph CHANNEL["Channel Service — Node.js (Render)"]
        QUEUE[Message Queue]
        PROV[Twilio / Resend / Simulator]
        CB[HMAC Webhook Emitter]
    end

    subgraph DB["Supabase — PostgreSQL (RLS on all tables)"]
        T1[(customers · orders · products)]
        T2[(personas · opportunities)]
        T3[(campaigns · communications · events)]
    end

    CSV[CSV Upload] -->|multipart| ONB
    ONB -->|POST /api/process-ingestion| ING
    ING --> T1
    T1 --> PER
    PER -->|LLM| T2
    T2 --> OPP_SVC
    OPP_SVC -->|LLM| T2
    T2 --> OPP
    OPP --> CAM
    CAM -->|LLM| CAM_SVC
    CAM_SVC --> T3
    CAM -->|launch| LAUNCH
    LAUNCH --> T3
    LAUNCH -->|transactional recipient outbox| QUEUE
    QUEUE --> PROV
    PROV --> CB
    CB -->|POST /webhooks/channel-status| WH
    WH --> T3
    T3 --> ANA

---

What I Built

Auth + Multi-Tenancy

• Supabase Auth — email/password with JWT-based sessions
• requireAuth middleware on every Express route — rejects requests without a valid JWT
• resolveCompanyMiddleware resolves companyId exclusively from the authenticated user's DB profile — never trusted from the client request
• Row-Level Security enforced by PostgreSQL for tenant-owned tables, backed by real cross-tenant integration tests
• Full multi-tenancy — multiple companies can sign up; all data is completely isolated

Data Ingestion Pipeline

• CSV upload (customers + orders) via bounded multipart requests, persisted as resumable ingestion sessions
• Idempotent Prisma upserts and batched PostgreSQL inserts for customers, products, orders, and line items
• RFM score computation: recency, frequency, monetary value per customer
• Customer attribute enrichment: average order value, category preferences, purchase intervals
• Persona assignment: LLM clusters customers into 4–6 behavioural archetypes per company
• Background processing — persona + agent setup is fire-and-forget; dashboard unlocks as soon as first opportunity is ready

AI Orchestration

Persisted AI generation uses a prompt → JSON parse → schema validate → DB write contract. Analytics uses deterministic aggregation and a safe fallback when an optional narrative call fails.

Step	Schema enforced	Fallback
Persona Engine	{ persona_name, description, reasoning }	Skip assignment, log
Opportunity Engine	Full typed opportunity object with numeric revenue fields	Discard, continue
Campaign Generator	{ name, message_content, channel, objective, offer }	Return error to frontend

Agent Orchestration

• An authenticated scheduler endpoint starts agent runs; overlapping ticks are rejected
• LangGraph persists campaign approval checkpoints in PostgreSQL and resumes after a human decision
• Involvement modes are typed and fail closed; no campaign sends without an approved state transition
• Agent runs and steps are persisted and surfaced in the activity feed

This is the beginning of the README. Read the rest at the original. Read the full README ↗