vortex

A multi-channel messaging SaaS platform that bridges messaging channels to GoClaw (self-hosted AI agent gateway). Store owners connect channels (Facebook Messenger, Instagram, TikTok, Shopee, Zalo) to their GoClaw instance for intelligent message routing and automation—positioned as a ManyChat alternative powered by AI agents instead of rule-based flows.

Tech Stack

• Monorepo: Turborepo
• Backend: NestJS, TypeScript, PostgreSQL, Prisma ORM
• Frontend: Next.js App Router (React 18+)
• Messaging Queue: BullMQ + Redis
• Real-time: WebSocket (ws library)
• Authentication: JWT + refresh token rotation
• Infrastructure: Docker, GitHub Actions

Project Structure

vortex/
├── apps/
│   ├── api/                    # NestJS backend (Port 3000)
│   │   ├── src/
│   │   │   ├── core/           # Auth, Store, Contact, Conversation, Queue, WS-GoClaw, Analytics
│   │   │   └── channels/       # Channel adapter interface & implementations
│   │   └── ...
│   └── web/                    # Next.js frontend (Port 3001)
├── packages/
│   ├── shared-types/           # Shared TypeScript types
│   └── shared-ui/              # Shared UI components (optional)
├── docs/                       # Project documentation
├── .claude/                    # Claude Code workflows & rules
└── plans/                      # Development plans & phase tracking

Documentation

• Project Overview & PDR — Vision, competitive positioning, success metrics, SDLC status
• Codebase Summary — Architecture, modules, interfaces, technology decisions
• Code Standards — NestJS/TypeScript conventions, naming, patterns, adapter guide
• System Architecture — Tenancy model, message pipeline, channel pattern, security
• Project Roadmap — Implementation phases, epics, milestones, missing docs checklist
• Design Guidelines — UI/UX direction, dashboard flows, wireframe status

Getting Started

Prerequisites: Node 18+, Docker (optional), PostgreSQL 14+

# Install dependencies
npm install

# Setup database
npm run db:setup

# Start development
npm run dev

See docs/codebase-summary.md for detailed project structure and initial module layout.

Development Workflow

1. Planning: Review ./plans/ for current implementation phase
2. Implementation: Follow Code Standards
3. Testing: Run test suite before commit
4. Documentation: Update relevant docs in ./docs/
5. Review: Code review + architecture alignment check

Key Decisions

• MVP Scope: Meta channels (FB Messenger, Instagram) only
• Tenancy: Shared Gateway (multi-tenant) — 1 NestJS gateway, each store connects to their own GoClaw instance
• Channel Pattern: Adapter pattern with auto-registration via NestJS DiscoveryService
• Architecture: Modular Monolith + Isolated Workers (BullMQ) for async processing

See System Architecture for detailed architectural diagrams and risk assessment.

Status

Current Phase: Late Phase 3 (System Design → Development planning)

Next milestone: Core modules + Meta channel adapter MVP

Support

For questions on architecture, see .claude/rules/ for development rules and workflows.