High-Level Architecture

Document Purpose: This document provides a comprehensive technical overview of the Cazo MVP system architecture, covering component design, integration flows, and security model.

1. System Architecture Overview

Cazo is built on a modern, layered microservices architecture designed for scalability and multi-tenancy.

flowchart TB
    subgraph Clients["Client Layer"]
        OD["Owner Dashboard<br/>(Next.js)"]
        BW["Booking Widget<br/>(Vanilla JS)"]
        MA["Mobile App<br/>(React Native)"]
        WA["WhatsApp<br/>(Meta API)"]
    end

    subgraph Gateway["API Gateway Layer"]
        KONG["Kong / Nginx"]
        AUTH["Auth Service<br/>(JWT + OTP)"]
        RL["Rate Limiter"]
    end

    subgraph Services["Core Services (FastAPI)"]
        BOOK["Booking Service"]
        CUST["Customer Service"]
        STAFF["Staff Service"]
        INV["Inventory Service"]
        PAY["Payment Service"]
        MKT["Marketing Service"]
    end

    subgraph AI["AI Engine Layer"]
        BOT["WhatsApp Bot<br/>(UC-BOT-*)"]
        NLP["NLP Service<br/>(Mistral 7B)"]
        NUDGE["Nudge Engine<br/>(n8n + Rules)"]
        LLM["LLM Fallback<br/>(GPT-4o)"]
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL<br/>(Multi-tenant)")]
        REDIS[("Redis<br/>(Cache/Sessions)")]
        VEC[("pgvector<br/>(Embeddings)")]
    end

    subgraph External["External Integrations"]
        META["Meta WhatsApp API"]
        RZPAY["Razorpay"]
        N8N["n8n Workflows"]
    end

    Clients --> Gateway
    Gateway --> Services
    Gateway --> AI
    Services --> Data
    AI --> Data
    AI --> External
    Services --> External

2. WhatsApp Bot Integration (20 UCs)

The WhatsApp Bot is the primary customer touchpoint, implementing a 3-tier AI approach.

sequenceDiagram
    participant C as Customer
    participant WA as WhatsApp
    participant META as Meta API
    participant BOT as Bot Service
    participant NLP as NLP Engine<br/>(Mistral 7B)
    participant LLM as GPT-4o<br/>(Fallback)
    participant CORE as Core Services
    participant AGENT as Human Agent

    C->>WA: Send message
    WA->>META: Webhook
    META->>BOT: Incoming message

    BOT->>NLP: Classify intent

    alt Confidence > 0.85
        NLP-->>BOT: Intent (BOOKING/CATALOG/FAQ)
        BOT->>CORE: Execute action
        CORE-->>BOT: Response data
        BOT-->>META: Reply message
    else Low Confidence
        BOT->>LLM: Complex query handling
        LLM-->>BOT: Generated response
        BOT-->>META: Reply message
    else Escalation Required
        BOT->>AGENT: Human handoff (UC-BOT-068)
        AGENT-->>C: Live support
    end

    META-->>WA: Deliver message
    WA-->>C: Display response

MVP Use Cases (20 Total)

Category	UC Range	Count	Capabilities
Commerce Core	UC-BOT-010 to 017	7	Catalog, Cart, Booking Confirmation
Drop-off Reduction	UC-BOT-020 to 023	4	Reschedule, Fallback, Recovery
Growth & Intelligence	UC-BOT-030 to 033	4	Analytics triggers
NLP & Safety	UC-BOT-060 to 068	9	Intent, Voice, Sentiment, Handoff

3. AI Nudge Engine Flow

The Nudge Engine transforms empty chairs into revenue through proactive customer engagement.

flowchart LR
    subgraph Sources["Data Sources"]
        BH[("Booking<br/>History")]
        CD[("Client<br/>Data")]
        SLOTS[("Slot<br/>Availability")]
    end

    subgraph Engine["n8n Rule Engine (L1)"]
        GAP["Gap Detection<br/>[SLOT-001]"]
        RFM["RFM Scoring"]
        TIMING["Timing Rules"]
    end

    subgraph Nudges["Nudge Triggers"]
        N1["Empty Chair Alert<br/>[NUDGE-001]"]
        N2["Re-booking Prompt<br/>[NUDGE-002]"]
        N3["Upsell Suggestion<br/>[NUDGE-003]"]
    end

    subgraph Delivery["Delivery"]
        WA["WhatsApp<br/>Template"]
        DASH["Owner<br/>Dashboard"]
    end

    Sources --> Engine
    Engine --> Nudges
    Nudges --> Delivery

Pragmatic AI Hierarchy

Tier	Technology	Use Case	Status
L1: Deterministic	n8n / SQL	Slot gap detection, Booking confirmation	MVP
L2: Specialized SLM	Mistral 7B	Intent extraction from WhatsApp	MVP
L3: Generalist LLM	GPT-4o API	Complex empathy, Angry customer handling	MVP (Fallback)

4. Payment Integration (Razorpay)

Full-stack payment processing from POS checkout to settlement.

sequenceDiagram
    participant FD as Front Desk
    participant POS as POS Service
    participant PAY as Payment Service
    participant RZP as Razorpay API
    participant INV as Invoice Service

    FD->>POS: Checkout (₹800)

    alt Wallet Redemption
        POS->>PAY: Check wallet balance
        PAY-->>POS: Available: ₹100
        POS->>POS: Deduct wallet
    end

    POS->>PAY: Process ₹700 (Split: Cash ₹200 + Card ₹500)

    alt Card Payment
        PAY->>RZP: Create order
        RZP-->>PAY: Order ID
        PAY->>RZP: Capture payment
        RZP-->>PAY: Payment confirmed
    end

    PAY->>INV: Generate GST invoice
    INV-->>FD: Invoice PDF (INV-2024-0001)

    Note over RZP,PAY: Webhook: payment.captured
    RZP->>PAY: Settlement notification

Payment Capabilities

UC ID	Capability	Priority
UC-FIN-001	Create Invoice	P0
UC-FIN-002	Apply Discount/Coupon	P0
UC-FIN-003	Accept Payment (UPI/Card)	P0
UC-FIN-006	Commission Calculation	P0
UC-FIN-008	GST Invoice Generation	P0

5. Security & Authentication Flow

Multi-layer security with OTP/OAuth authentication and RBAC enforcement.

flowchart TB
    subgraph Auth["Authentication"]
        LOGIN["Login Request"]
        OTP["OTP Verification"]
        OAUTH["OAuth (Google)"]
        JWT["JWT Issuance"]
    end

    subgraph Gateway["API Gateway"]
        VERIFY["Token Verification"]
        RBAC["RBAC Check"]
        TENANT["Tenant Isolation"]
    end

    subgraph Roles["Role-Based Access"]
        OWNER["Owner<br/>Full Access"]
        MGR["Manager<br/>Ops + Staff"]
        FD["Front Desk<br/>Booking + Check-in"]
        STYLIST["Stylist<br/>Own Schedule"]
    end

    subgraph Protection["Security Controls"]
        RATE["Rate Limiting"]
        AUDIT["Audit Logging"]
        ENC["Data Encryption"]
    end

    LOGIN --> OTP & OAUTH
    OTP & OAUTH --> JWT
    JWT --> VERIFY
    VERIFY --> RBAC
    RBAC --> TENANT
    TENANT --> Roles
    Gateway -.-> Protection

RBAC Matrix

Role	Dashboard	Financials	Staff Mgmt	Settings
Owner	Yes	Yes	Yes	Yes
Manager	Yes	No	Yes	No
Front Desk	Yes	No	No	No
Stylist	Own Only	Own Only	No	No

6. MVP vs Phase 2+ Components

Clear delineation of MVP scope (93 UCs) versus deferred features.

flowchart TB
    subgraph MVP["Phase 1: MVP (93 UCs)"]
        direction TB
        M1["Core Platform (15)"]
        M2["Customer Interface (9)"]
        M3["Front Desk (14)"]
        M4["Marketing Studio (6)"]
        M5["Finance & POS (9)"]
        M6["AI Layer (12)"]
        M7["WhatsApp Bot (20)"]
        M8["Analytics (4)"]
        M9["Owner Dashboard (1)"]
    end

    subgraph P2["Phase 2+ (Deferred)"]
        direction TB
        D1["Bot Onboarding (4)"]
        D2["In-Chat Payments"]
        D3["Engagement & Retention (5)"]
        D4["Platform Ops (5)"]
        D5["Vision AI"]
        D6["Self-Orchestrating Agent"]
    end

    MVP -.->|"After MVP Stable"| P2

Phase Breakdown

Phase	Focus	Use Cases
Phase 1 (MVP)	Core Ops + AI Nudges + Bot	93
Phase 2	Deferred MVP + Integrations	~137
Phase 3	Enterprise Features	~100
Phase 4	Innovation & Vision AI	~90

Key Technology Stack

Layer	Component	Technology
Frontend	Owner Dashboard	Next.js (React)
	Booking Widget	Vanilla JS / React
	Mobile App	React Native (Expo)
Backend	API Gateway	Kong / Nginx
	Core Services	Python FastAPI
	AI Engine	LangChain + Ollama
Data	Primary DB	PostgreSQL
	Cache	Redis
	Vector DB	pgvector
External	Payments	Razorpay
	Messaging	Meta WhatsApp API
	Workflows	n8n

8. Development & Deployment Setup

Complete tooling and configuration required for MVP development and deployment.

8.1 Development Environment

Category	Tool	Config File	Purpose
Containerization	Docker	`Dockerfile`, `docker-compose.yml`	Local dev, service isolation
Package Mgmt	pip / Poetry	`requirements.txt`, `pyproject.toml`	Python dependencies
Node.js	npm / pnpm	`package.json`	Frontend dependencies
Version Control	Git	`.gitignore`, `.gitattributes`	Source control
Code Quality	Ruff / Black	`pyproject.toml`	Python linting/formatting
	ESLint / Prettier	`.eslintrc`, `.prettierrc`	JS/TS linting/formatting

8.2 Backend Services Configuration

Service	Config Files	Environment Variables
FastAPI	`main.py`, `config.py`	`DATABASE_URL`, `REDIS_URL`, `SECRET_KEY`
PostgreSQL	`postgresql.conf`, `pg_hba.conf`	`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`
Redis	`redis.conf`	`REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`
Kong Gateway	`kong.yml`	`KONG_DATABASE`, `KONG_PG_HOST`

8.3 AI/ML Infrastructure

Component	Config	Environment Variables
Ollama	Model pull: `mistral:7b`	`OLLAMA_HOST`, `OLLAMA_ORIGINS`
OpenAI (Fallback)	LangChain config	`OPENAI_API_KEY`, `OPENAI_ORG_ID`
pgvector	PostgreSQL extension	`VECTOR_DIMENSIONS=1536`
n8n Workflows	Workflow JSON exports	`N8N_WEBHOOK_URL`, `N8N_ENCRYPTION_KEY`

8.4 External Integrations

Integration	Config Required	Credentials
Razorpay	Webhook endpoints, GST config	`RAZORPAY_KEY_ID`, `RAZORPAY_KEY_SECRET`, `RAZORPAY_WEBHOOK_SECRET`
Meta WhatsApp	Business account, templates	`WHATSAPP_TOKEN`, `WHATSAPP_PHONE_ID`, `WHATSAPP_VERIFY_TOKEN`
OTP Provider	SMS templates	`MSG91_AUTH_KEY` or `TWILIO_SID`, `TWILIO_AUTH_TOKEN`
OAuth (Google)	OAuth consent screen	`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`

8.5 Infrastructure & Deployment

Component	Tool	Config
Cloud	AWS EC2 (g5.xlarge for GPU)	Security groups, IAM roles
Secrets	AWS SSM / HashiCorp Vault	Parameter Store paths
CI/CD	GitHub Actions	`.github/workflows/*.yml`
Monitoring	CloudWatch / Prometheus	Alert rules, dashboards
Logging	Loki / CloudWatch Logs	Log groups, retention
APM	Sentry / OpenTelemetry	`SENTRY_DSN`, trace config

8.6 Mobile App (React Native)

Config	File	Purpose
Expo Config	`app.json`, `eas.json`	App metadata, build profiles
API Config	`config.ts`	Backend URLs per environment
Push Notifications	Expo credentials	FCM/APNs setup

8.7 Environment Matrix

Environment	Purpose	Database	AI Model
Local	Development	PostgreSQL (Docker)	Ollama (local)
Staging	Testing	RDS PostgreSQL	Ollama (EC2)
Production	Live	RDS PostgreSQL (Multi-AZ)	Ollama (EC2 g5) + GPT-4o fallback

Cross-References

MVP Scope Document: Detailed use case breakdown
AI & ML Overview: Pragmatic AI strategy
WhatsApp Bot Use Cases: 20 MVP use cases
Finance & Payments: POS and billing
Core Platform Security: RBAC details