Pre-cleanup commit: Current state before service layer consolidation
This commit is contained in:
463
ARCHITECTURE_DIAGRAMS.md
Normal file
463
ARCHITECTURE_DIAGRAMS.md
Normal file
@@ -0,0 +1,463 @@
|
||||
# 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 │ (documentAiGenkitProcessor 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.
|
||||
Reference in New Issue
Block a user