> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> System architecture overview for the Mahalaxmi Traders platform

## Tech Stack

| Layer          | Technology                                                      |
| -------------- | --------------------------------------------------------------- |
| Frontend       | React 18, TypeScript, Vite, Tailwind CSS, Radix UI              |
| Backend        | Node.js, Express.js, TypeScript                                 |
| Database       | MySQL 8 (Drizzle ORM)                                           |
| Caching        | Redis (Upstash in production)                                   |
| Auth           | JWT access + refresh tokens, OAuth2 (Google, Twitter, Facebook) |
| AI / LLM       | Google Gemini, LangChain, OpenAI (embeddings)                   |
| Vector DB      | Qdrant (RAG / semantic search)                                  |
| Cloud Storage  | AWS S3                                                          |
| Payments       | Stripe, Cashfree                                                |
| WhatsApp       | Gupshup (primary), Wasimple, Facebook Meta                      |
| Real-time      | WebSockets                                                      |
| Job Scheduling | node-cron                                                       |

***

## High-Level Architecture

```
Browser / WhatsApp / Telegram / Gmail / Twitter
        │
        ▼
  Express.js Server (port 5001)
  ├── REST API (~160+ endpoints)  ←── JWT Auth middleware
  ├── WebSocket Server            ←── Real-time inbox updates
  ├── Webhook handlers            ←── Gupshup / Wasimple / Meta / Stripe
  └── Static file server          ←── Vite-built React app
        │
        ├── MySQL 8 (Drizzle ORM)
        ├── Redis (session cache, job queue)
        ├── AWS S3 (media + training files)
        ├── Qdrant (vector store for RAG)
        └── AI Agent Process (port 5555)
              └── LangChain + Gemini / OpenAI
```

***

## Project Structure

```
sahyogi/
├── client/src/           # React frontend
│   ├── pages/            # Route-level components
│   ├── components/       # Shared UI components
│   ├── hooks/            # Custom React hooks
│   └── lib/              # API clients, utilities
│
├── server/               # Express backend
│   ├── routes.ts         # All API routes (160+ endpoints)
│   ├── db.ts             # MySQL connection pool
│   ├── jwt-auth.ts       # JWT middleware
│   ├── storage.ts        # DB query/mutation layer
│   ├── stripe.ts         # Stripe client + webhooks
│   ├── websocket.ts      # WebSocket server
│   ├── cron.ts           # Scheduled jobs
│   └── utils/            # vectorSearch, encryption, events
│
├── shared/
│   ├── schema.ts         # Drizzle schema + Zod types (source of truth)
│   ├── gupshup.ts        # Gupshup API client
│   └── wasimple.ts       # Wasimple API client
│
├── agent/                # Standalone AI agent (port 5555)
└── db/                   # Migrations + seed
```

***

## Key Flows

### Message Flow (WhatsApp → Bot → User)

```
WhatsApp user sends message
        │
        ▼
Gupshup/Wasimple/Meta webhook → POST /api/webhooks/...
        │
        ▼
Bot lookup (channel → bot mapping)
        │
        ▼
AI Agent (LangChain + Gemini)
  ├── Tool calls (Airtable, webhooks, API tools)
  └── RAG: Qdrant vector search → context injection
        │
        ▼
Response sent back via WhatsApp provider API
        │
        ▼
Message stored in MySQL → WebSocket push to inbox
```

### RAG (Knowledge Base) Flow

```
User uploads PDF / URL
        │
        ▼
File stored in AWS S3 / URL scraped
        │
        ▼
processTrainingFiles.ts / processTrainingUrls.ts
  → Text chunked → Embeddings via Gemini/OpenAI
  → Stored in Qdrant vector collection
        │
        ▼
On bot message → vectorSearch.ts queries Qdrant
  → Top-k chunks injected into LLM prompt
```

***

## Channels

| Channel                  | Provider          | Auth method |
| ------------------------ | ----------------- | ----------- |
| WhatsApp                 | Gupshup (primary) | API Key     |
| WhatsApp                 | Wasimple          | API Key     |
| WhatsApp                 | Facebook/Meta     | OAuth2      |
| Gmail                    | Google            | OAuth2      |
| Twitter                  | Twitter           | OAuth2      |
| Web                      | Built-in          | Bot ID      |
| Telegram, Slack, Discord | On request        | —           |

***

## AI & Integrations

| Service       | Role                                        |
| ------------- | ------------------------------------------- |
| Google Gemini | LLM for bot responses + embeddings          |
| OpenAI        | Embedding fallback                          |
| Qdrant        | Vector search for knowledge-base RAG        |
| LangChain     | Agent orchestration, tool use, RAG pipeline |
| Airtable      | Bot tool — read/write CRM data              |
| AWS S3        | Media and training file storage             |
| Stripe        | Subscription billing                        |
| Cashfree      | Alternative billing (India)                 |
| Redis         | Session caching, queue                      |