admin/cim_summary
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
cim_summary/.planning/codebase/STACK.md
admin e6e1b1fa6f docs: map existing codebase
2026-02-24 10:28:22 -05:00

6.4 KiB
Raw Permalink Blame History

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

Reference in New Issue View Git Blame Copy Permalink