# CIM Document Processor - Architecture Diagrams ## System Architecture Overview ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ FRONTEND (React) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Login │ │ Document │ │ Document │ │ Analytics │ │ │ │ Form │ │ Upload │ │ List │ │ Dashboard │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Document │ │ Upload │ │ Protected │ │ Auth │ │ │ │ Viewer │ │ Monitoring │ │ Route │ │ Context │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ HTTP/HTTPS ┌─────────────────────────────────────────────────────────────────────────────┐ │ BACKEND (Node.js) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Document │ │ Vector │ │ Monitoring │ │ Auth │ │ │ │ Routes │ │ Routes │ │ Routes │ │ Middleware │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Unified │ │ Optimized │ │ LLM │ │ PDF │ │ │ │ Document │ │ Agentic │ │ Service │ │ Generation │ │ │ │ Processor │ │ RAG │ │ │ │ Service │ │ │ │ │ │ Processor │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ File │ │ Upload │ │ Session │ │ Job Queue │ │ │ │ Storage │ │ Monitoring │ │ Service │ │ Service │ │ │ │ Service │ │ Service │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ EXTERNAL SERVICES │ ├─────────────────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Google │ │ Google │ │ Anthropic │ │ Firebase │ │ │ │ Document AI │ │ Cloud │ │ Claude AI │ │ Auth │ │ │ │ │ │ Storage │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ DATABASE (Supabase) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Documents │ │ Agentic │ │ Document │ │ Vector │ │ │ │ Table │ │ RAG │ │ Chunks │ │ Embeddings │ │ │ │ │ │ Sessions │ │ Table │ │ Table │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Document Processing Flow ``` ┌─────────────────┐ │ User Uploads │ │ PDF Document │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 1. Get Upload │ ──► Generate signed URL from Google Cloud Storage │ URL │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 2. Upload to │ ──► Direct upload to GCS bucket │ GCS │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 3. Confirm │ ──► Update database, create processing job │ Upload │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 4. Text │ ──► Google Document AI extracts text from PDF │ Extraction │ (documentAiProcessor or direct Document AI) └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 5. Intelligent │ ──► Split text into semantic chunks (4000 chars) │ Chunking │ with 200 char overlap └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 6. Vector │ ──► Generate embeddings for each chunk │ Embedding │ (rate-limited to 5 concurrent calls) └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 7. LLM Analysis │ ──► llmService → Claude AI analyzes chunks │ │ and generates structured CIM review data └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 8. PDF │ ──► pdfGenerationService generates summary PDF │ Generation │ using Puppeteer └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 9. Database │ ──► Store analysis data, update document status │ Storage │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ 10. Complete │ ──► Update session, notify user, cleanup │ Processing │ └─────────────────┘ ``` ## Error Handling Flow ``` Processing Error │ ▼ ┌─────────────────┐ │ Error Logging │ ──► Log error with correlation ID └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ Retry Logic │ ──► Retry failed operation (up to 3 times) └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ Graceful │ ──► Return partial results or error message │ Degradation │ └─────────────────┘ ``` ## Component Dependency Map ### Backend Services ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ CORE SERVICES │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Unified │ │ Optimized │ │ LLM Service │ │ │ │ Document │───►│ Agentic RAG │───►│ │ │ │ │ Processor │ │ Processor │ │ (Claude AI/ │ │ │ │ (Orchestrator) │ │ (Core AI) │ │ OpenAI) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ PDF Generation │ │ File Storage │ │ Upload │ │ │ │ Service │ │ Service │ │ Monitoring │ │ │ │ (Puppeteer) │ │ (GCS) │ │ Service │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Session │ │ Job Queue │ │ Upload │ │ │ │ Service │ │ Service │ │ Progress │ │ │ │ (Auth Mgmt) │ │ (Background) │ │ Service │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Frontend Components ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ FRONTEND COMPONENTS │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ App.tsx │ │ AuthContext │ │ ProtectedRoute │ │ │ │ (Main App) │───►│ (Auth State) │───►│ (Route Guard) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ DocumentUpload │ │ DocumentList │ │ DocumentViewer │ │ │ │ (File Upload) │ │ (Document Mgmt) │ │ (View Results) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Analytics │ │ Upload │ │ LoginForm │ │ │ │ (Dashboard) │ │ Monitoring │ │ (Auth) │ │ │ │ │ │ Dashboard │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Service Dependencies Map ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ SERVICE DEPENDENCIES │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ │ │ │ unifiedDocumentProcessor (Main Orchestrator) │ │ └─────────┬───────┘ │ │ │ │ │ ├───► optimizedAgenticRAGProcessor │ │ │ ├───► llmService (AI Processing) │ │ │ ├───► vectorDatabaseService (Embeddings) │ │ │ └───► fileStorageService (File Operations) │ │ │ │ │ ├───► pdfGenerationService (PDF Creation) │ │ │ └───► Puppeteer (PDF Generation) │ │ │ │ │ ├───► uploadMonitoringService (Real-time Tracking) │ │ │ │ │ ├───► sessionService (Session Management) │ │ │ │ │ └───► jobQueueService (Background Processing) │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## API Endpoint Map ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ API ENDPOINTS │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ DOCUMENT ROUTES │ │ │ │ │ │ │ │ POST /documents/upload-url ──► Get signed upload URL │ │ │ │ POST /documents/:id/confirm-upload ──► Confirm upload & process │ │ │ │ POST /documents/:id/process-optimized-agentic-rag ──► AI processing │ │ │ │ GET /documents/:id/download ──► Download PDF │ │ │ │ DELETE /documents/:id ──► Delete document │ │ │ │ GET /documents/analytics ──► Get analytics │ │ │ │ GET /documents/:id/agentic-rag-sessions ──► Get sessions │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ MONITORING ROUTES │ │ │ │ │ │ │ │ GET /monitoring/dashboard ──► Get monitoring dashboard │ │ │ │ GET /monitoring/upload-metrics ──► Get upload metrics │ │ │ │ GET /monitoring/upload-health ──► Get health status │ │ │ │ GET /monitoring/real-time-stats ──► Get real-time stats │ │ │ │ GET /monitoring/error-analysis ──► Get error analysis │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ VECTOR ROUTES │ │ │ │ │ │ │ │ GET /vector/document-chunks/:documentId ──► Get document chunks │ │ │ │ GET /vector/analytics ──► Get vector analytics │ │ │ │ GET /vector/stats ──► Get vector stats │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Database Schema Map ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ DATABASE SCHEMA │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ DOCUMENTS TABLE │ │ │ │ │ │ │ │ id (UUID) ──► Primary key │ │ │ │ user_id (TEXT) ──► User identifier │ │ │ │ original_file_name (TEXT) ──► Original filename │ │ │ │ file_path (TEXT) ──► GCS file path │ │ │ │ file_size (INTEGER) ──► File size in bytes │ │ │ │ status (TEXT) ──► Processing status │ │ │ │ extracted_text (TEXT) ──► Extracted text content │ │ │ │ generated_summary (TEXT) ──► Generated summary │ │ │ │ summary_pdf_path (TEXT) ──► PDF summary path │ │ │ │ analysis_data (JSONB) ──► Structured analysis data │ │ │ │ created_at (TIMESTAMP) ──► Creation timestamp │ │ │ │ updated_at (TIMESTAMP) ──► Last update timestamp │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ AGENTIC RAG SESSIONS TABLE │ │ │ │ │ │ │ │ id (UUID) ──► Primary key │ │ │ │ document_id (UUID) ──► Foreign key to documents │ │ │ │ strategy (TEXT) ──► Processing strategy used │ │ │ │ status (TEXT) ──► Session status │ │ │ │ total_agents (INTEGER) ──► Total agents in session │ │ │ │ completed_agents (INTEGER) ──► Completed agents │ │ │ │ failed_agents (INTEGER) ──► Failed agents │ │ │ │ overall_validation_score (DECIMAL) ──► Quality score │ │ │ │ processing_time_ms (INTEGER) ──► Processing time │ │ │ │ api_calls_count (INTEGER) ──► Number of API calls │ │ │ │ total_cost (DECIMAL) ──► Total processing cost │ │ │ │ created_at (TIMESTAMP) ──► Creation timestamp │ │ │ │ completed_at (TIMESTAMP) ──► Completion timestamp │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ DOCUMENT CHUNKS TABLE │ │ │ │ │ │ │ │ id (UUID) ──► Primary key │ │ │ │ document_id (UUID) ──► Foreign key to documents │ │ │ │ content (TEXT) ──► Chunk content │ │ │ │ embedding (VECTOR(1536)) ──► Vector embedding │ │ │ │ chunk_index (INTEGER) ──► Chunk order │ │ │ │ metadata (JSONB) ──► Chunk metadata │ │ │ │ created_at (TIMESTAMP) ──► Creation timestamp │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## File Structure Map ``` cim_summary/ ├── backend/ │ ├── src/ │ │ ├── config/ # Configuration files │ │ ├── controllers/ # Request handlers │ │ ├── middleware/ # Express middleware │ │ ├── models/ # Database models │ │ ├── routes/ # API route definitions │ │ ├── services/ # Business logic services │ │ │ ├── unifiedDocumentProcessor.ts # Main orchestrator │ │ │ ├── optimizedAgenticRAGProcessor.ts # Core AI processing │ │ │ ├── llmService.ts # LLM interactions │ │ │ ├── pdfGenerationService.ts # PDF generation │ │ │ ├── fileStorageService.ts # GCS operations │ │ │ ├── uploadMonitoringService.ts # Real-time tracking │ │ │ ├── sessionService.ts # Session management │ │ │ ├── jobQueueService.ts # Background processing │ │ │ └── uploadProgressService.ts # Progress tracking │ │ ├── utils/ # Utility functions │ │ └── index.ts # Main entry point │ ├── scripts/ # Setup and utility scripts │ └── package.json # Backend dependencies ├── frontend/ │ ├── src/ │ │ ├── components/ # React components │ │ ├── contexts/ # React contexts │ │ ├── services/ # API service layer │ │ ├── utils/ # Utility functions │ │ ├── config/ # Frontend configuration │ │ ├── App.tsx # Main app component │ │ └── main.tsx # App entry point │ └── package.json # Frontend dependencies └── README.md # Project documentation ``` ## Key Data Flow Sequences ### 1. User Authentication Flow ``` User → LoginForm → Firebase Auth → AuthContext → ProtectedRoute → Dashboard ``` ### 2. Document Upload Flow ``` User → DocumentUpload → documentService.uploadDocument() → Backend /upload-url → GCS signed URL → Frontend upload → Backend /confirm-upload → Database update → Processing trigger ``` ### 3. Document Processing Flow ``` Processing trigger → unifiedDocumentProcessor → optimizedAgenticRAGProcessor → Document AI → Chunking → Embeddings → llmService → Claude AI → pdfGenerationService → PDF Generation → Database update → User notification ``` ### 4. Analytics Flow ``` User → Analytics component → documentService.getAnalytics() → Backend /analytics → agenticRAGDatabaseService → Database queries → Structured analytics data → Frontend display ``` ### 5. Error Handling Flow ``` Error occurs → Error logging with correlation ID → Retry logic (up to 3 attempts) → Graceful degradation → User notification ``` ## Processing Pipeline Details ### LLM Service Integration ``` optimizedAgenticRAGProcessor │ ▼ ┌─────────────────┐ │ llmService │ ──► Model selection based on task complexity └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ Claude AI │ ──► Primary model (claude-3-opus-20240229) │ (Anthropic) │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ OpenAI │ ──► Fallback model (if Claude fails) │ (GPT-4) │ └─────────────────┘ ``` ### PDF Generation Pipeline ``` Analysis Data │ ▼ ┌─────────────────┐ │ pdfGenerationService.generateCIMReviewPDF() │ └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ HTML Generation │ ──► Convert analysis data to HTML └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ Puppeteer │ ──► Convert HTML to PDF └─────────┬───────┘ │ ▼ ┌─────────────────┐ │ PDF Buffer │ ──► Return PDF as buffer for download └─────────────────┘ ``` This architecture provides a clear separation of concerns, scalable design, and comprehensive monitoring capabilities for the CIM Document Processor application.