463 lines
36 KiB
Markdown
463 lines
36 KiB
Markdown
# 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. |