QueryNox Backend - Technical Architecture Documentation

System Overview

Technical Stack

Core Framework & Infrastructure

Authentication & Authorization

Monitoring & Observability

AI Provider Integrations

Architecture Deep Dive

Service Layer Architecture

Database Schema Design

User Document Structure

{
 _id: String, // Clerk User ID (primary key)
 chats: [ObjectId], // Array of chat references
 bookmarkedChats: [ObjectId], // Bookmarked chat references
 productId: String, // Subscription product reference
 usedChatGeneration: Number, // Monthly usage counter
 usedImageGeneration: Number, // Monthly image generation counter
 usedWebSearch: Number, // Monthly web search counter
 usedFileRag: Number, // Monthly RAG usage counter
 limitsUpdatedAt: Number, // Last reset timestamp
 createdAt: Number, // Account creation timestamp
 updatedAt: Number // Last modification timestamp
}

Chat Document Structure

{
 _id: ObjectId, // Auto-generated chat ID
 userId: String, // User reference (Clerk ID)
 title: String, // Auto-generated chat title
 chatName: String, // AI-generated descriptive name
 model: String, // Current model being used
 systemPrompt: String, // System instructions
 webSearch: Boolean, // Web search enabled flag
 isShared: Boolean, // Public sharing flag
 createdAt: Number, // Chat creation timestamp
 updatedAt: Number // Last activity timestamp
}

ChatQuery Document Structure

{
 _id: ObjectId, // Auto-generated query ID
 chatId: ObjectId, // Parent chat reference
 prompt: String, // User input prompt
 model: String, // Model used for response
 systemPrompt: String, // System prompt at time of query
 webSearch: Boolean, // Web search used flag
 response: String, // AI model response
 meta: Map<String, String>, // Metadata (image keys, etc.)
 createdAt: Number, // Query timestamp
 updatedAt: Number // Response completion timestamp
}

Product Document Structure (Subscription Management)

{
 _id: String, // Polar product ID
 name: String, // Product display name
 description: String, // Product description
 metadata: {
 chatGenerationLimit: Number, // Monthly chat limit
 imageGenerationLimit: Number, // Monthly image limit
 webSearchLimit: Number, // Monthly web search limit
 fileRagLimit: Number, // Monthly RAG limit
 fileCountLimit: Number // Per-request file limit
 },
 recurringInterval: String, // Billing cycle (month/year)
 isRecurring: Boolean, // Subscription flag
 isArchived: Boolean, // Product active state
 organizationId: String, // Polar organization ID
 createdAt: Number, // Product creation
 modifiedAt: Number, // Last modification
 prices: Array, // Pricing tiers
 benefits: Array, // Feature list
 medias: Array, // Product media
 attachedCustomFields: Array // Additional metadata
}

Request Processing Pipeline

1. Authentication Flow

// Clerk Authentication Middleware
const clerkAuthMiddleware = (requestUser = false, upInsert = true) => {
 return async (req, res, next) => {
 let userId = getAuth(req).userId;
 
 // Development bypass
 if (!userId && process.env.NODE_ENV === "development") {
 userId = req.query.userId;
 }
 
 if (!userId) {
 return res.status(401).json({ error: 'Not authenticated' });
 }
 
 if (requestUser) {
 let _user = await User.findById(userId);
 if (!_user && upInsert) {
 _user = new User({ _id: userId }); // Auto-create user
 }
 req.user = _user;
 }
 
 req.userId = userId;
 next();
 };
};

2. Rate Limiting Implementation

// Monthly usage-based rate limiting
const userLimitMiddleware = () => {
 return async (req, res, next) => {
 const user = req.user;
 const { model, webSearch } = req.body;
 const files = req.files;
 
 // Monthly reset logic
 const now = new Date();
 const lastUpdated = new Date(user.limitsUpdatedAt);
 
 if (now.getMonth() !== lastUpdated.getMonth() || 
 now.getFullYear() !== lastUpdated.getFullYear()) {
 // Reset all counters
 user.usedChatGeneration = 0;
 user.usedFileRag = 0;
 user.usedImageGeneration = 0;
 user.usedWebSearch = 0;
 user.limitsUpdatedAt = Date.now();
 await user.save();
 }
 
 // Apply limits based on subscription tier
 const limits = user.productId ? 
 await getProductLimits(user.productId) : 
 DEFAULT_LIMITS;
 
 // Validate usage against limits
 if (exceedsLimits(user, limits, req)) {
 return res.status(429).json({ error: 'Usage limit exceeded' });
 }
 
 next();
 };
};

AI Service Architecture

Service Manager Pattern

class ServiceManager {
 constructor() {
 this.openRouterService = openRouterService;
 this.aiService = aiService;
 this.ragService = ragService;
 this.webSearchService = webSearchService;
 this.imageService = imageService;
 }
 // Intelligent routing based on model type
 isOpenRouterModel(modelName) {
 return ['gpt-oss-120b', 'grok-3-mini'].includes(modelName);
 }
 async* generateStreamingResponse(model, messages, systemPrompt) {
 if (this.isOpenRouterModel(model)) {
 yield* this.openRouterService.generateStreamingResponse(model, messages, systemPrompt);
 } else {
 yield* this.aiService.generateStreamingResponse(model, messages, systemPrompt);
 }
 }
}

Model Configuration

const models = [
 {
 name: "Claude 3.5 Sonnet",
 fullName: "claude-haiku-4-5-20251001",
 category: "Text Generation",
 description: "Fast and efficient text generation",
 limit: 200000,
 pro: true
 },
 {
 name: "llama-3.3-70b-versatile",
 fullName: "llama-3.3-70b-versatile",
 category: "Text Generation", 
 description: "Powerful open-source model via Groq",
 limit: 32768,
 pro: false
 },
 {
 name: "gpt-3.5-turbo",
 fullName: "gpt-3.5-turbo",
 category: "Text Generation",
 description: "Reliable and versatile text generation",
 limit: 16385,
 pro: false
 },
 {
 name: "gemini-2.5-flash",
 fullName: "gemini-2.5-flash",
 category: "Text Generation",
 description: "Google's advanced language model",
 limit: 1000000,
 pro: false
 },
 {
 name: "gpt-image-1-mini",
 fullName: "gpt-image-1-mini",
 category: "Image Generation",
 description: "High-quality image generation",
 limit: 4000,
 pro: false
 },
 {
 name: "gpt-oss-120b",
 fullName: "gpt-oss-120b",
 category: "Text Generation",
 description: "OpenAI Open Source 120B Model",
 limit: 128000,
 pro: false
 },
 {
 name: "grok-3-mini",
 fullName: "grok-3-mini",
 category: "Text Generation",
 description: "X.AI Grok 3 Mini Model", 
 limit: 128000,
 pro: true
 }
];

RAG (Retrieval-Augmented Generation) Implementation

Document Processing Pipeline

const ragService = {
 // PDF text extraction using pdf-parse
 getTextFromPDF: async (pdfBuffer) => {
 const data = await pdf(pdfBuffer);
 return data.text;
 },
 // Semantic chunking with overlap
 chunkText: (text, chunkSize = 1000) => {
 const paragraphs = text.split(/\n\s*\n/);
 const chunks = [];
 let currentChunk = '';
 
 for (const paragraph of paragraphs) {
 if (currentChunk.length + paragraph.length > chunkSize) {
 chunks.push(currentChunk);
 currentChunk = '';
 }
 currentChunk += paragraph + '\n\n';
 }
 chunks.push(currentChunk);
 return chunks;
 },
 // OpenAI embeddings with batch processing
 getEmbeddings: async (chunks) => {
 const response = await openai.embeddings.create({
 model: 'text-embedding-3-small',
 input: chunks,
 });
 return response.data.map(item => item.embedding);
 },
 // Cosine similarity search with top-K retrieval
 findRelevantChunks: (promptEmbedding, chunkEmbeddings, chunks, topK = 3) => {
 const cosSimilarity = (vecA, vecB) => {
 let dotProduct = 0;
 let normA = 0;
 let normB = 0;
 
 for (let i = 0; i < vecA.length; i++) {
 dotProduct += vecA[i] * vecB[i];
 normA += vecA[i] * vecA[i];
 normB += vecB[i] * vecB[i];
 }
 
 return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
 };
 const similarities = chunkEmbeddings.map(chunkVec => 
 cosSimilarity(promptEmbedding, chunkVec)
 );
 
 return similarities
 .map((score, index) => ({ score, chunk: chunks[index] }))
 .sort((a, b) => b.score - a.score)
 .slice(0, topK)
 .map(item => item.chunk);
 },
 // OCR processing with Tesseract.js
 getTextFromImage: async (imageBuffer, mimetype = 'image/jpeg') => {
 try {
 const base64Image = imageBuffer.toString('base64');
 const dataUrl = `data:${mimetype};base64,${base64Image}`;
 
 const result = await Tesseract.recognize(dataUrl, 'eng', {
 logger: () => {} // Silent mode
 });
 
 const extractedText = result.data.text.trim();
 return extractedText || 'No text found in image.';
 } catch (error) {
 return 'Unable to extract text from image.';
 }
 }
};

Web Search Integration

Google Custom Search Implementation

const webSearchService = {
 search: async (messages) => {
 try {
 if (!process.env.GOOGLE_API_KEY || !process.env.GOOGLE_SEARCH_ENGINE_ID) {
 return '';
 }
 // Generate contextual search query
 const query = await openRouterService.generateContextForWebSearch(messages);
 const response = await axios.get('https://www.googleapis.com/customsearch/v1', {
 params: {
 key: process.env.GOOGLE_API_KEY,
 cx: process.env.GOOGLE_SEARCH_ENGINE_ID,
 q: query,
 num: 3,
 },
 timeout: 10000,
 });
 const searchResults = response.data.items?.slice(0, 3).map(item => ({
 title: item.title,
 snippet: item.snippet,
 link: item.link
 }));
 if (!searchResults || searchResults.length === 0) {
 return '';
 }
 const context = searchResults.map(r => 
 `Title: ${r.title}\nSnippet: ${r.snippet}\nLink: ${r.link}`
 ).join('\n\n');
 return `\n\n--- Relevant information from web search ---\n${context}\n\n--- End of web search results ---`;
 } catch (error) {
 return ''; // Fail gracefully
 }
 }
};

Streaming Response Implementation

Server-Sent Events (SSE) Architecture

const handleChatStreamCombined = async (req, res) => {
 try {
 const { prompt, model, systemPrompt, webSearch } = req.body;
 const user = req.user;
 const { chatId } = req.params;
 const files = req.files;
 // Set SSE headers
 res.writeHead(200, {
 'Content-Type': 'text/event-stream',
 'Cache-Control': 'no-cache',
 'Connection': 'keep-alive',
 'Access-Control-Allow-Origin': '*',
 });
 const sendEvent = (data) => {
 res.write(`data: ${JSON.stringify(data)}\n\n`);
 if (res.flush) res.flush();
 };
 // Processing pipeline with status updates
 sendEvent({ type: 'status', message: 'Loading chat...' });
 
 // Chat creation/retrieval
 let chat = chatId ? await Chat.findById(chatId) : 
 new Chat({ userId: user._id, title: prompt.substring(0, 50) });
 sendEvent({ type: 'metadata', chatId: chat._id, chatName: chat.chatName });
 // Context building
 sendEvent({ type: 'status', message: 'Loading conversation history...' });
 const previousQueries = await ChatQuery.find({ chatId: chat._id }).sort({ createdAt: 1 });
 
 let context = '';
 
 // Web search augmentation
 if (webSearch) {
 sendEvent({ type: 'status', message: 'Searching the web...' });
 context += await webSearchService.search([...conversationHistory, { role: 'user', content: prompt }]);
 user.usedWebSearch++;
 sendEvent({ type: 'status', message: 'Web search completed.' });
 }
 // File processing
 if (files && files.length > 0) {
 sendEvent({ type: 'status', message: `Processing ${files.length} file(s)...` });
 context += await ragService.getContextFromFiles(prompt, files);
 user.usedFileRag++;
 sendEvent({ type: 'status', message: 'File processing completed.' });
 }
 sendEvent({ type: 'status', message: 'Generating AI response...' });
 // Streaming AI response
 let fullResponse = { content: "" };
 for await (const chunk of serviceManager.generateStreamingResponse(model, messages, systemPrompt)) {
 const { content, ...rest } = chunk;
 fullResponse = { ...rest, content: fullResponse.content + chunk.content };
 sendEvent({ type: 'content', content: chunk.content });
 }
 // Finalization
 await saveChatQuery(chat, prompt, model, fullResponse);
 sendEvent({ type: 'complete', chatQuery, chat });
 } catch (error) {
 sendEvent({ type: 'error', error: error.message });
 }
 
 res.end();
};

Image Generation & Storage

Cloudflare R2 Integration

const imageService = {
 generateImage: async (prompt, userId) => {
 try {
 // Generate image with DALL-E
 const response = await openai.images.generate({
 model: process.env.MODEL_GPT_IMAGE,
 prompt: prompt,
 n: 1,
 size: '1024x1024',
 quality: "standard",
 response_format: "b64_json"
 });
 const image_bytes = Buffer.from(response.data[0].b64_json, "base64");
 const id = `${Date.now()}-${crypto.randomUUID()}.png`;
 const key = `generation/${userId}/${id}`;
 // Upload to R2 (S3-compatible)
 await r2client.send(new PutObjectCommand({
 Bucket: process.env.R2_BUCKET,
 Key: key,
 Body: image_bytes.buffer,
 ContentType: 'image/png',
 }));
 // Generate URLs
 const previewUrl = `${process.env.PUBLIC_BUCKET_URL}/${key}`;
 const downloadUrl = `${process.env.BACKEND_HOST}/api/v1/public/images/download/${encodeURIComponent(key)}`;
 return {
 success: true,
 filename: id,
 key: key,
 previewUrl: previewUrl,
 downloadUrl: downloadUrl
 };
 } catch (error) {
 return { success: false, error: error.message };
 }
 }
};

Payment & Subscription Management

Polar Integration

const paymentController = {
 handleCheckout: async (req, res) => {
 try {
 const { productId } = req.params;
 const userId = req.userId;
 
 // Get Clerk user info
 const clerkUser = await clerkClient.users.getUser(userId);
 
 // Create or get Polar customer
 let customer;
 try {
 customer = await polar.customers.getExternal({ externalId: userId });
 } catch (err) {
 customer = await polar.customers.create({
 email: clerkUser.emailAddresses[0].emailAddress,
 externalId: userId,
 name: clerkUser.fullName,
 });
 }
 
 // Create checkout session
 const checkout = await polar.checkouts.create({
 products: [productId],
 successUrl: `${callback}?checkout_id={CHECKOUT_ID}`,
 customerId: customer.id,
 customerEmail: customer.email,
 customerName: customer.name,
 externalCustomerId: userId,
 customerBillingAddress: { country: "IN" },
 metadata: { externalCustomerId: customer.externalId }
 });
 
 res.json({ url: checkout.url });
 } catch (err) {
 res.status(500).json({ error: "Checkout creation failed" });
 }
 },
 webhook: {
 handleSubscriptionActive: async (req, res) => {
 const data = req.event.data;
 await User.updateOne(
 { _id: data.customer.externalId },
 { productId: data.product.id },
 { upsert: true }
 );
 res.status(200).end();
 },
 handleSubscriptionRevoked: async (req, res) => {
 const data = req.event.data;
 await User.updateOne(
 { _id: data.metadata.externalCustomerId },
 { productId: null }
 );
 res.status(200).end();
 }
 }
};

Monitoring & Observability

Custom Metrics Collection

// Prometheus metrics configuration
const reqResMetrics = new promClient.Histogram({
 name: "http_express_req_res_time",
 help: "Tells how much time taken by req and res.",
 labelNames: ["method", 'route', 'status_code', 'first_time_to_byte', 'last_time_to_byte', 'content_length'],
 buckets: [1, 50, 100, 200, 400, 600, 800, 1000, 1500, 2000]
});
const totalRequestCounter = new promClient.Counter({
 name: "total_requests",
 help: "Counts total number of requests handled by server."
});
// Morgan custom formatter for structured logging
morgan.format("dev-with-time", function (tokens, req, res) {
 const status_code = Number(tokens.status(req, res));
 const method = tokens.method(req, res);
 const first_time_to_byte = parseFloat(tokens["response-time"](req, res)) || 0;
 const last_time_to_byte = parseFloat(tokens["total-time"](req, res)) || 0;
 const content_length = parseFloat(tokens.res(req, res, "content-length")) || 0;
 const route = tokens.url(req, res);
 return JSON.stringify({ method, status_code, first_time_to_byte, last_time_to_byte, route, content_length });
});

Winston + Loki Logging

const logger = createLogger({
 level: process.env.NODE_ENV !== "production" ? "silly" : "http",
 format: format.combine(
 format.timestamp(),
 format.errors({ stack: true }),
 format.splat(),
 format.json()
 ),
 transports: [
 new transports.File({ filename: "logs/error.log", level: "error" }),
 new transports.File({ filename: "logs/combined.log" }),
 new LokiTransport({
 level: "http",
 labels: { app: "express", service: "querynox_backend" },
 host: process.env.LOKI_LOGGER_HOST,
 basicAuth: `${process.env.LOKI_USER}:${process.env.LOKI_API_KEY}`,
 batching: true,
 interval: 5,
 json: true
 })
 ]
});

Security Implementation

CORS Configuration

app.use(cors({
 origin: [
 process.env.LOKI_LOGGER_HOST,
 process.env.FRONTEND_HOST,
 "http://localhost:5173",
 "https://querynox-dev.vercel.app",
 "https://www.querynox.xyz",
 "https://3.134.238.10",
 "https://3.129.111.220",
 "https://52.15.118.168"
 ],
 credentials: true
}));

Request Size Limits & File Upload Security

// Dynamic body parser based on route
app.use((req, res, next) => {
 if (req.url.includes('webhook')) {
 express.raw({ type: 'application/json' })(req, res, next);
 } else {
 express.json({ limit: "10mb" })(req, res, next);
 }
});
// Multer configuration for secure file uploads
const storage = multer.memoryStorage();
const upload = multer({
 storage: storage,
 limits: { fileSize: 5 * 1024 * 1024 } // 5MB limit
});

API Endpoint Structure

Chat Endpoints

POST /api/v1/chat # Create new chat
POST /api/v1/chat/:chatId # Continue existing chat
POST /api/v1/chat/stream # Create new streaming chat
POST /api/v1/chat/:chatId/stream # Continue streaming chat
GET /api/v1/chat/models # List available models
GET /api/v1/chat/user # Get user's chats
GET /api/v1/chat/:chatId # Get chat history
PATCH /api/v1/chat/:chatId/share # Toggle chat sharing
PATCH /api/v1/chat/:chatId/bookmark # Toggle bookmark
DELETE /api/v1/chat/:chatId # Delete chat

User Endpoints

GET /api/v1/user # Get user info
GET /api/v1/user/bookmarked-chats # Get bookmarked chats

Payment Endpoints

GET /api/v1/payments/checkout/:productId # Create checkout session
GET /api/v1/payments/status/:checkoutId # Validate checkout
GET /api/v1/payments/portal # Customer portal
POST /api/v1/payments/webhook # Webhook handler

Public Endpoints

GET /api/v1/public/chat/:chatId # Get shared chat (rate-limited)
GET /api/v1/public/images/download/:key # Download image

Admin Endpoints

GET /metrics # Prometheus metrics (basic auth)
GET /health # Health check
GET /help # API documentation

Environment Configuration

Required Environment Variables

# Database
MONGODB_URI=mongodb://localhost:27017/querynox
# Authentication
CLERK_SECRET_KEY=your_clerk_secret_key
# AI Providers
OPENAI_API_KEY=your_openai_api_key
CLAUDE_API_KEY=your_anthropic_api_key
GROQ_API_KEY=your_groq_api_key
GEMINI_API_KEY=your_google_gemini_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
# Search
GOOGLE_API_KEY=your_google_search_api_key
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id
# Storage
R2_ACCESS_KEY_ID=your_cloudflare_r2_access_key
R2_SECRET_ACCESS_KEY=your_cloudflare_r2_secret_key
R2_BUCKET=your_bucket_name
CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
PUBLIC_BUCKET_URL=https://your-bucket-url.com
# Payments
POLAR_ACCESS_TOKEN=your_polar_access_token
POLAR_WEBHOOK_SECRET=your_webhook_secret
# Monitoring
LOKI_LOGGER_HOST=your_loki_host
LOKI_USER=your_loki_user
LOKI_API_KEY=your_loki_api_key
# Server
PORT=8080
NODE_ENV=production
BACKEND_HOST=https://your-domain.com
FRONTEND_HOST=https://your-frontend.com
# Admin
USERNAME=admin_username
PASSWORD=admin_password

Performance Optimizations

1. Database Indexing Strategy

// User model indexes
userSchema.index({ productId: 1 });
// Chat model indexes 
chatSchema.index({ userId: 1, createdAt: -1 });
// ChatQuery model indexes
chatQuerySchema.index({ chatId: 1, createdAt: -1 });
// Product model indexes
productSchema.index({ organizationId: 1, isArchived: 1 });

2. Memory Management

// Conversation history management
if (messages.length > MAX_MESSAGE_SIZE) {
 const oldMessages = messages.slice(0, messages.length - MAX_MESSAGE_SIZE);
 const recentMessages = messages.slice(-MAX_MESSAGE_SIZE);
 
 // Generate summary from old messages to preserve context
 const summary = await serviceManager.generateConversationSummary(oldMessages);
 
 messages = [
 { role: "user", content: summary },
 { role: "assistant", content: "summary noted." },
 ...recentMessages
 ];
}

3. Response Compression

// Conditional compression (skip for streaming)
app.use((req, res, next) => {
 if (req.path.endsWith('stream')) {
 next();
 } else {
 compression()(req, res, next);
 }
});

4. Request Caching (Public Endpoints)

// 30-second in-memory cache for public shared chats
const cache = new Map();
const cacheTtlMs = 30 * 1000;
function withCache(handler) {
 return async (req, res) => {
 const key = `public_chat_${req.params.chatId}`;
 const cached = cache.get(key);
 const now = Date.now();
 
 if (cached && cached.expiresAt > now) {
 res.set('Cache-Control', 'public, max-age=30');
 return res.status(200).json(cached.data);
 }
 
 // Execute handler and cache result
 const result = await handler(req, res);
 if (res.statusCode === 200) {
 cache.set(key, { data: result, expiresAt: now + cacheTtlMs });
 }
 
 return result;
 };
}

Error Handling & Resilience

1. Graceful Error Handling

// Global error handler
app.use((err, req, res, next) => {
 logger.error(err);
 res.status(500).json({ error: err.message || String(err) });
});
// Service-level error handling with fallbacks
async generateResponse(model, messages, systemPrompt) {
 try {
 if (this.isOpenRouterModel(model)) {
 return await this.openRouterService.generateResponse(model, messages, systemPrompt);
 } else {
 return await this.aiService.generateResponse(model, messages, systemPrompt);
 }
 } catch (error) {
 logger.error(`Service Manager Error for model ${model}:`, error);
 
 // Fallback to default model
 if (model !== 'gpt-3.5-turbo') {
 logger.info(`Falling back to gpt-3.5-turbo for failed model: ${model}`);
 return await this.aiService.generateResponse('gpt-3.5-turbo', messages, systemPrompt);
 }
 
 throw error;
 }
}

2. Database Connection Resilience

const connectDB = async () => {
 let retrys = 1;
 while (retrys < MAX_DATABASE_RETRY) {
 try {
 await mongoose.connect(process.env.MONGODB_URI);
 logger.info("Connected to Database");
 return;
 } catch (error) {
 if (retrys < MAX_DATABASE_RETRY) {
 logger.info(`Retrying ${retrys}...`);
 retrys++;
 await new Promise(resolve => setTimeout(resolve, 2000 * retrys)); // Exponential backoff
 } else {
 logger.error(`Connection failed to database after ${MAX_DATABASE_RETRY} attempts.`);
 process.exit(1);
 }
 }
 }
};

Deployment Architecture

Docker Compose Setup

services:
 prometheus-server:
 image: prom/prometheus
 ports:
 - 9090:9090
 volumes:
 - ./prometheus.yml:/etc/prometheus/prometheus.yml
 grafana-server:
 image: grafana/grafana-oss
 ports:
 - 3000:3000
 loki-server:
 image: grafana/loki
 ports:
 - 3100:3100

Prometheus Configuration

global:
 scrape_interval: 4s
scrape_configs:
 - job_name: prometheus
 static_configs:
 - targets: ["0.0.0.0:8080"]
 metrics_path: /metrics
 basic_auth:
 username: ${USERNAME}
 password: ${PASSWORD}

System Limits & Constraints

File Upload Constraints

const constraints = {
 fileSize: "5MB per file",
 fileCount: "10 files per request (configurable per user tier)",
 totalRequestSize: "10MB",
 supportedFormats: ["PDF", "JPG", "PNG", "GIF", "BMP", "TIFF"]
};

Rate Limiting

const rateLimits = {
 publicEndpoints: "20 requests per 30 seconds per IP",
 authenticatedEndpoints: "Based on subscription tier",
 
 freeUsers: {
 chatGeneration: "200 per month",
 imageGeneration: "8 per month", 
 webSearch: "10 per month",
 fileRag: "10 per month",
 fileCount: "1 per request"
 },
 
 proUsers: {
 chatGeneration: "Configurable per product",
 imageGeneration: "Configurable per product",
 webSearch: "Configurable per product", 
 fileRag: "Configurable per product",
 fileCount: "Configurable per product"
 }
};

Model Context Limits

const contextLimits = {
 "gpt-3.5-turbo": 16385,
 "claude-haiku-4-5-20251001": 200000,
 "llama-3.3-70b-versatile": 32768,
 "gemini-2.5-flash": 1000000,
 "gpt-oss-120b": 128000,
 "grok-3-mini": 128000,
 "gpt-image-1-mini": 4000
};

Integration Points

External Service Dependencies

Service Health Monitoring

async healthCheck() {
 const health = {
 openRouter: false,
 originalAI: false, 
 rag: false,
 webSearch: false,
 image: false,
 database: false,
 storage: false
 };
 // Test each service with lightweight requests
 try {
 await this.openRouterService.generateChatCompletion('gpt-oss-120b', [
 { role: 'user', content: 'Hello' }
 ], { maxTokens: 1 });
 health.openRouter = true;
 } catch (error) {
 logger.warn('OpenRouter health check failed:', error.message);
 }
 // ... similar checks for other services
 return health;
}

Performance Metrics

Key Performance Indicators

const performanceMetrics = {
 averageResponseTime: "< 2 seconds for text generation",
 streamingLatency: "< 100ms for first token",
 imageGeneration: "< 30 seconds",
 fileProcessing: "< 5 seconds per MB",
 webSearch: "< 10 seconds",
 databaseQueries: "< 100ms for reads, < 500ms for writes",
 uptime: "> 99.9%",
 concurrentUsers: "1000+ simultaneous connections",
 throughput: "100+ requests per second"
};

Future Enhancements & Scalability

Planned Features

Scalability Considerations

Troubleshooting Guide

Common Issues & Solutions

Development Guidelines

Code Quality Standards

Testing Strategy