How hrshimpi/cf_ai_data-analyzer works
Project Type and Purpose
• Orion Data Analyzer is a full-stack, single-user web application for AI-powered Excel/CSV data analysis.
• The frontend is built in React + TypeScript (Vite) and runs in the browser.
• The backend is written in Go using the Fiber framework, exposing RESTful endpoints that orchestrate file parsing and calls to Google Vertex AI (Gemini).
File Structure Analysis
• Top-level
• main.go: backend entry point
• Dockerfile/.dockerignore, .gitignore: containerization & VCS
• go.mod/go.sum: Go module
• frontend/: React app
• backend/: Fiber app
• Backend
• handlers/: HTTP handlers for /upload, /suggestions, /analyze, /contextual-suggestions, /health
• services/: core business logic (file parsing, analysis engine, Gemini integration)
• models/: request/response data models
• middleware/: logger, recovery, request ID
• utils/: error handling, validation, response formatting
• Frontend
• src/pages/: top-level views (Landing, Home, Dashboard)
• src/components/: reusable UI (FileUpload, PromptInput, ChatHistory, ChartRenderer, etc.)
• src/api/: client wrapper for backend endpoints
• src/context/: global state (AppContext, reducer)
• src/utils: localStorage for chat persistence
• Vite config, tsconfig, env example
Key Architecture Insights from README
• Single-page app (SPA) that stores chat threads in localStorage (no backend DB).
• Two-step AI agent flow:
1. Analysis engine reasons over data → suggestions
2. Chart generator returns JSON chart specs.
• File uploads stored temporarily on disk (storage/temp/).
• External dependency: Google Vertex AI (Gemini models).
• Deployment: Dockerized backend (Cloud Run), static frontend hosting.
a. Main Components
• Browser (React SPA)
• UI Components
• LocalStorage (chat thread persistence)
• Backend (Go Fiber)
• HTTP Server & Middleware
• Handlers (upload, suggestions, analyze, contextual-suggestions, health)
• Services (FileParser, AnalysisEngine, GeminiClient)
• Temp Storage (storage/temp/)
• External Service
• Google Vertex AI (Gemini models)
b. Data Flow & Interactions
1. User uploads file via FileUpload component → POST /upload → FileParser parses CSV/XLSX → temp storage
2. User requests suggestions (POST /suggestions) → AnalysisEngine uses parsed data → calls Gemini → returns natural-language suggestions
3. User asks follow-up (POST /contextual-suggestions) → handler passes chat history + new prompt to Gemini
4. User requests chart analysis (POST /analyze) → AnalysisEngine → ChartGenerator flow → Gemini → JSON chart spec → frontend’s ChartRenderer
5. Frontend persists chat threads in localStorage for 24-hour expiry
c. Architectural Patterns & Principles
• Layered architecture: Presentation (React) → API (Fiber handlers) → Business Logic (services) → External AI service
• Separation of concerns: parsing, AI orchestration, HTTP handling, error/response utils
• Stateless backend (no user sessions)
• Graceful fallback: text insights on chart failure
• Retry mechanism in AnalysisEngine (up to 3 attempts)
d. Technologies & Frameworks
• Frontend: React, TypeScript, Vite, npm
• Backend: Go, Fiber, Google Cloud SDK, Vertex AI
• Containerization: Docker, Cloud Run
• Storage: local disk for temp files, browser localStorage
Detailed Capturing of Elements
• Retry logic and fallback in AnalysisEngine.
• Environment variable dependencies (e.g., VITE_API_URL, GOOGLE_CLOUD_PROJECT_ID).
• “Health” endpoint for monitoring.