cim_summary/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-02-24

Languages

Primary:

• TypeScript 5.2.2 - Both backend and frontend, strict mode enabled
• JavaScript (CommonJS) - Build outputs and configuration

Supporting:

• SQL - Supabase PostgreSQL database via migrations in backend/src/models/migrations/

Runtime

Environment:

• Node.js 20 (specified in backend/firebase.json)
• Browser (ES2020 target for both client and server)

Package Manager:

• npm - Primary package manager for both backend and frontend
• Lockfile: package-lock.json present in both backend/ and frontend/

Frameworks

Backend - Core:

• Express.js 4.18.2 - HTTP server and REST API framework at backend/src/index.ts
• Firebase Admin SDK 13.4.0 - Authentication and service account management at backend/src/config/firebase.ts
• Firebase Functions 6.4.0 - Cloud Functions deployment runtime at port 5001

Frontend - Core:

• React 18.2.0 - UI framework with TypeScript support
• Vite 4.5.0 - Build tool and dev server (port 5173 for dev, port 3000 production)

Backend - Testing:

• Vitest 2.1.0 - Test runner with v8 coverage provider at backend/vitest.config.ts
• Configuration: Global test environment set to 'node', 30-second test timeout

Backend - Build/Dev:

• ts-node 10.9.2 - TypeScript execution for scripts
• ts-node-dev 2.0.0 - Live reload development server with --transpile-only flag
• TypeScript Compiler (tsc) 5.2.2 - Strict type checking, ES2020 target

Frontend - Build/Dev:

• Vite React plugin 4.1.1 - React JSX transformation
• TailwindCSS 3.3.5 - Utility-first CSS framework with PostCSS 8.4.31

Key Dependencies

Critical Infrastructure:

• @google-cloud/documentai 9.3.0 - Google Document AI OCR/text extraction at backend/src/services/documentAiProcessor.ts
• @google-cloud/storage 7.16.0 - Google Cloud Storage (GCS) for file uploads and processing
• @supabase/supabase-js 2.53.0 - PostgreSQL database client with vector support at backend/src/config/supabase.ts
• pg 8.11.3 - Direct PostgreSQL connection pool for critical operations bypassing PostgREST

LLM & AI:

• @anthropic-ai/sdk 0.57.0 - Claude API integration with support for Anthropic provider
• openai 5.10.2 - OpenAI API and embeddings (text-embedding-3-small)
• Both providers abstracted via backend/src/services/llmService.ts

PDF Processing:

• pdf-lib 1.17.1 - PDF generation and manipulation at backend/src/services/pdfGenerationService.ts
• pdf-parse 1.1.1 - PDF text extraction
• pdfkit 0.17.1 - PDF document creation

Document Processing:

• puppeteer 21.11.0 - Headless Chrome for HTML/PDF conversion

Security & Authentication:

• firebase 12.0.0 (frontend) - Firebase client SDK for authentication at frontend/src/config/firebase.ts
• firebase-admin 13.4.0 (backend) - Admin SDK for token verification at backend/src/middleware/firebaseAuth.ts
• jsonwebtoken 9.0.2 - JWT token creation and verification
• bcryptjs 2.4.3 - Password hashing with 12 rounds default

API & HTTP:

• axios 1.11.0 - HTTP client for both frontend and backend
• cors 2.8.5 - Cross-Origin Resource Sharing middleware for Express
• helmet 7.1.0 - Security headers middleware
• morgan 1.10.0 - HTTP request logging middleware
• express-rate-limit 7.1.5 - Rate limiting middleware (1000 requests per 15 minutes)

Data Validation & Schema:

• zod 3.25.76 - TypeScript-first schema validation at backend/src/services/llmSchemas.ts
• zod-to-json-schema 3.24.6 - Convert Zod schemas to JSON Schema for LLM structured output
• joi 17.11.0 - Environment variable validation in backend/src/config/env.ts

Logging & Monitoring:

• winston 3.11.0 - Structured logging framework with multiple transports at backend/src/utils/logger.ts

Frontend - UI Components:

• lucide-react 0.294.0 - Icon library
• react-dom 18.2.0 - React rendering for web
• react-router-dom 6.20.1 - Client-side routing
• react-dropzone 14.3.8 - File upload handling
• clsx 2.0.0 - Conditional className utility
• tailwind-merge 2.0.0 - Merge Tailwind classes with conflict resolution

Utilities:

• uuid 11.1.0 - Unique identifier generation
• dotenv 16.3.1 - Environment variable loading from .env files

Configuration

Environment:

• .env file support - Dotenv loads from .env for local development in backend/src/config/env.ts
• Environment validation - Joi schema at backend/src/config/env.ts validates all required/optional env vars
• Firebase Functions v2 - Uses defineString() and defineSecret() for secure configuration (migration from v1 functions.config())

Key Configuration Variables (Backend):

• NODE_ENV - 'development' | 'production' | 'test'
• LLM_PROVIDER - 'openai' | 'anthropic' | 'openrouter' (default: 'openai')
• GCLOUD_PROJECT_ID - Google Cloud project ID (required)
• DOCUMENT_AI_PROCESSOR_ID - Document AI processor ID (required)
• GCS_BUCKET_NAME - Google Cloud Storage bucket (required)
• SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY - Supabase PostgreSQL connection
• DATABASE_URL - Direct PostgreSQL connection string for bypass operations
• OPENAI_API_KEY - OpenAI API key for embeddings and models
• ANTHROPIC_API_KEY - Anthropic Claude API key
• OPENROUTER_API_KEY - OpenRouter API key (optional, uses BYOK with Anthropic key)

Key Configuration Variables (Frontend):

• VITE_API_BASE_URL - Backend API endpoint
• VITE_FIREBASE_* - Firebase configuration (API key, auth domain, project ID, etc.)

Build Configuration:

• Backend: backend/tsconfig.json - Strict TypeScript, CommonJS module output, ES2020 target
• Frontend: frontend/tsconfig.json - ES2020 target, JSX React support, path alias @/*
• Firebase: backend/firebase.json - Node.js 20 runtime, Firebase Functions emulator on port 5001

Platform Requirements

Development:

• Node.js 20.x
• npm 9+
• Google Cloud credentials (for Document AI and GCS)
• Firebase project credentials (service account key)
• Supabase project URL and keys

Production:

• Backend: Firebase Cloud Functions (Node.js 20 runtime) or Google Cloud Run
• Frontend: Firebase Hosting (CDN-backed static hosting)
• Database: Supabase PostgreSQL with pgvector extension for vector search
• Storage: Google Cloud Storage for documents and generated PDFs
• Memory Limits: Backend configured with --max-old-space-size=8192 for large document processing

---

Stack analysis: 2026-02-24