Overview
Brainstormer V2 is a modern AI chatbot platform built with a microservices architecture, using Next.js 15 for the frontend and Fastify-based Node.js microservices for the backend.System Architecture
Layer Breakdown
1. Frontend Layer (Next.js 15)
Technology
Next.js 15, React 19, TypeScript 5, TailwindCSS
Port
3000
- Server-Side Rendering (SSR) for optimal performance
- Turbopack for fast development builds
- Component-based architecture with reusable UI components
- Multi-path agent onboarding (
classicandcreatorflows)
2. API Gateway (Fastify)
Port: 4000 Responsibilities:- Route requests to appropriate microservices
- CORS configuration and security
- Rate limiting and request validation
- Health check aggregation
3. Microservices Layer
4. Infrastructure Layer
5. External Services
Data Flow Diagrams
User Authentication Flow
AI Chat Message Flow
Billing and Credit Accounting Flow
Knowledge Base RAG Flow
1
Ingest Content
User uploads document or adds URL source. Frontend sends to Knowledge Service via Gateway.
2
Resolve Connector
ConnectorRegistry resolves source to the appropriate ContentConnector (YouTube, Instagram, Twitter, RSS, URL, blog-platform, or document).
3
Normalize Content
Connector fetches and returns
NormalizedContent[] with dedup keys and content hashes. For social media: one kb_document per post with metadata.4
Process Media
Vision text extraction (OpenRouter) for images/PDFs. Transcription service for audio/video content. Text chunking with metadata preservation.
5
Generate Embeddings
Gemini Embedding 2 generates multimodal embeddings (3072 dimensions) for text, images, video, and audio content.
6
Store Vectors
Vectors stored in ChromaDB (local) or Pinecone (production). Metadata saved to PostgreSQL.
7
Query and Retrieve
User queries KB. Service generates query embedding, retrieves chunks, and Bot Service uses chunks as context for OpenRouter. AI generates response with enriched citations.
Knowledge Graph Flow
Security
Authentication
Authentication
- JWT-based authentication
- Secure password hashing (bcrypt)
- Token refresh mechanism
- Multi-tenant isolation
Data Protection
Data Protection
- AES-256-GCM encryption for sensitive config values
- Parameterized SQL queries (no ORM)
- HTTPS in production
- Token-based file access with expiration
Deployment
All services run under Docker Compose. There are three environments:main auto-deploys to the development server. Production is manual only — no auto-deploy from any branch.