Skip to main content

​
System overview

SupaProxy is a multi-repo system with four repositories:
RepoPurposeTech
supaproxy-serverHono API serverHono + TypeScript + MySQL + Redis
supaproxy-sdkTypeScript SDK (@supaproxy/sdk)TypeScript
supaproxy-dashboardFrontendAstro 6 + React 19 + Tailwind CSS 4
supaproxy-docsDocumentation (this site)Mintlify

​
How the pieces connect

Dashboard (Astro + React)
    │
    ├── imports @supaproxy/sdk
    │         │
    │         └── typed methods + entities
    │
    ▼
Server (Hono)
    ├── /api/* endpoints
    ├── MySQL (persistent state)
    ├── Redis + BullMQ (job queues)
    └── MCP servers (tool execution)
The SDK wraps every server endpoint with typed methods. The dashboard imports the SDK; it never calls fetch against the server directly.

​
Server architecture

src/
├── index.ts              Server entry point, route mounting
├── config.ts             Env var loading (requireEnv, no fallbacks)
├── shared/               Types, entities, API contracts
├── middleware/
│   ├── auth.ts           JWT cookie verification (requireAuth)
│   └── validate.ts       Zod schema validation (parseBody)
├── routes/               Modular Hono sub-apps
├── core/                 Business logic
│   ├── agent.ts          AI + MCP tool orchestration
│   ├── lifecycle.ts      Conversation transitions (BullMQ)
│   ├── workspace.ts      Workspace operations
│   └── conversation.ts   Conversation CRUD
├── consumers/
│   └── slack.ts          Slack Socket Mode listener
├── auth/                 Auth services
├── db/                   MySQL pool, migrations, types
└── observability/        Audit logging

​
Stack

LayerTechnology
ServerHono 4.7 + TypeScript
AuthJWT cookies (httpOnly, secure in production)
ValidationZod schemas
DatabaseMySQL 8
QueueRedis 7 + BullMQ
AIAnthropic Claude (configurable)
MCP@modelcontextprotocol/sdk (HTTP + STDIO)
Consumers@slack/bolt (Socket Mode)
FrontendAstro 6 + React 19
StylingTailwind CSS 4 + CSS variables
SDK@supaproxy/sdk (TypeScript)

​
Message flow

Consumer (Slack, API, WhatsApp)
    │
    ▼
Server receives message
    │
    ▼
Route validates input, finds workspace
    │
    ▼
Core creates/extends conversation
    │
    ▼
Agent connects to MCP servers, discovers tools
    │
    ▼
Agent loop: query → tool calls → results → repeat
    │
    ▼
Response returned to consumer
    │
    ▼
Audit log recorded (who, what, cost, duration)

​
Background jobs

Three BullMQ queues handle asynchronous work:
QueuePurpose
lifecycleTransition conversations: open → cold → closed
cold-messagesGenerate and send check-in messages for cold conversations
conversation-statsGenerate sentiment, category, resolution, and cost analysis