Platform Stack
Five Services
CollectHive runs as a multi-container stack. The admin-ui serves the React frontend through nginx, handling authentication and preview proxying. The memory-mcp is the Express API server — memory storage, skill orchestration, and the MCP protocol bridge. The postgres service runs PostgreSQL with pgvector, providing the primary data store for memory-mcp including vector embeddings for semantic search. The sandbox provides isolated Python execution for agent skills, kept separate so untrusted code never touches the host. Convex runs in its own compose stack for real-time data sync, connected via a dedicated Docker bridge network.
Docker Networks
Four networks isolate traffic: beehave-internal connects admin-ui and memory-mcp, beehave-web exposes the frontend, beehave-preview routes to ephemeral dev containers, and beehave-convex-bridge links to the Convex backend. A docker-socket-proxy restricts container API access in production, and a convex-restarter handles backend recovery.
Three Environments
The stack runs identically across local development (your Mac, port 3000), staging (auto-deployed on push to the staging branch), and production (manual deploy via workflow dispatch). Same compose structure, different Clerk apps and image tags.
Product Stack
Every app built on CollectHive uses the same stack for consistency across prototypes and production.
| Layer | Choice | Version |
|---|---|---|
| Frontend | Vite (React SPA) | 6.x |
| UI | React | 18.3.x |
| Styling | Tailwind CSS | 3.4.x |
| Backend | Convex | ^1.31.x |
| Auth | Clerk | 5.x |
| Language | TypeScript | 5.7.x |
| Icons | lucide-react | 0.462.x |
Vite is the default. Convex replaces what you’d normally need Next.js server features for — API routes, data fetching, real-time subscriptions. Vite also works out of the box with dev containers (reads PREVIEW_BASE_PATH at runtime), produces smaller images (~50MB nginx vs ~180MB Node.js), and is what Convex officially recommends.
Next.js is the exception — only when the app has public-facing pages that need SEO, Open Graph link previews, or server-side rendering.
Tailwind 3, not 4. Tailwind 4 requires native Rust addons that don’t work in WebContainers (the browser-based dev environments used for previews). Tailwind 3 works everywhere.
Technical Detail — Backend Defaults
Convex is the default backend. It provides a real-time reactive database, serverless functions (queries, mutations, actions), type-safe schema with validators, file storage, cron jobs, vector search, and Clerk auth integration via JWT templates. No separate database provisioning, ORM, or migration tooling needed.
PostgreSQL is the exception — only justified when two or more of these apply: heavy Python data pipelines with raw SQL, pgvector embeddings with complex similarity queries, complex relational queries (CTEs, window functions, multi-table JOINs), or regulatory requirements for self-hosted data.
Credentials are stored encrypted in Convex, per-user. Tools retrieve credentials server-side inside their handlers — never injected into agent context, never returned to the agent.