36 KiB
36 KiB
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.