# hrshimpi/cf_ai_data-analyzer architecture

> Architecture diagram of the GitHub repository hrshimpi/cf_ai_data-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hrshimpi/cf_ai_data-analyzer
- Repository: https://github.com/hrshimpi/cf_ai_data-analyzer

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction BT
        browser["Browser (React SPA)"]:::client
        FileUpload["FileUpload Component"]:::component
        PromptInput["PromptInput Component"]:::component
        ChatHistory["ChatHistory Component"]:::component
        ChartRenderer["ChartRenderer Component"]:::component
        SuggestionsComp["Suggestions Component"]:::component
        ContextualSuggestions["ContextualSuggestions Component"]:::component
        ErrorBoundary["ErrorBoundary Component"]:::component
        LandingPage["Landing Page"]:::page
        HomePage["Home Page"]:::page
        DashboardPage["Dashboard Page"]:::page
        AppContext["AppContext (Global State)"]:::state
        LocalStorage["LocalStorage"]:::storage
        APIClient["API Client Wrapper"]:::api
    end

    %% API Layer
    subgraph "API Layer"
        direction BT
        Server["Fiber HTTP Server"]:::service
        MiddlewareChain["Middleware Chain\n(requestID → logger → recovery)"]:::middleware
        UploadHandler["/upload Handler"]:::handler
        SuggestionsHandler["/suggestions Handler"]:::handler
        ContextualHandler["/contextual-suggestions Handler"]:::handler
        AnalyzeHandler["/analyze Handler"]:::handler
        HealthHandler["/health Handler"]:::handler
    end

    %% Service Layer
    subgraph "Service Layer"
        direction BT
        FileParser["FileParser Service"]:::service
        AnalysisEngine["AnalysisEngine Service\n(retry up to 3, fallback)"]:::service
        ChartGenerator["ChartGenerator"]:::service
        GeminiClient["GeminiClient Service"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction BT
        TempStorage["Temp File Store"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction BT
        VertexAI["Vertex AI (Gemini)"]:::external
    end

    %% Client Interactions
    browser --> FileUpload
    browser --> PromptInput
    browser --> ChatHistory
    browser --> ChartRenderer
    browser --> SuggestionsComp
    browser --> ContextualSuggestions
    browser --> ErrorBoundary
    browser --> LandingPage
    browser --> HomePage
    browser --> DashboardPage
    browser --> AppContext
    browser --> LocalStorage

    FileUpload --> APIClient
    PromptInput --> APIClient
    SuggestionsComp --> APIClient
    ContextualSuggestions --> APIClient
    ChartRenderer --> APIClient

    LocalStorage --- browser

    %% API Requests
    APIClient --> Server
    Server --> MiddlewareChain
    MiddlewareChain --> UploadHandler
    MiddlewareChain --> SuggestionsHandler
    MiddlewareChain --> ContextualHandler
    MiddlewareChain --> AnalyzeHandler
    MiddlewareChain --> HealthHandler

    %% Handler to Service Calls
    UploadHandler --> FileParser
    SuggestionsHandler --> AnalysisEngine
    ContextualHandler --> AnalysisEngine
    AnalyzeHandler --> AnalysisEngine

    AnalysisEngine --> GeminiClient
    ChartGenerator --> GeminiClient

    GeminiClient --> VertexAI

    FileParser --> TempStorage

    AnalysisEngine --> ChartGenerator

    %% Click Events
    click browser "https://github.com/hrshimpi/cf_ai_data-analyzer/tree/main/frontend/src"
    click FileUpload "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/FileUpload.tsx"
    click PromptInput "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/PromptInput.tsx"
    click ChatHistory "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/ChatHistory.tsx"
    click ChartRenderer "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/ChartRenderer.tsx"
    click SuggestionsComp "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/Suggestions.tsx"
    click ContextualSuggestions "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/ContextualSuggestions.tsx"
    click ErrorBoundary "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/components/ErrorBoundary.tsx"
    click LandingPage "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/pages/Landing.tsx"
    click HomePage "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/pages/Home.tsx"
    click DashboardPage "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/pages/Dashboard.tsx"
    click AppContext "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/context/AppContext.tsx"
    click APIClient "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/api/backend.ts"
    click LocalStorage "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/utils/localStorage.ts"
    click browser "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/frontend/src/main.tsx"
    click Server "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/main.go"
    click MiddlewareChain "https://github.com/hrshimpi/cf_ai_data-analyzer/tree/main/backend/middleware"
    click UploadHandler "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/handlers/upload.go"
    click SuggestionsHandler "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/handlers/suggestions.go"
    click ContextualHandler "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/handlers/contextual_suggestions.go"
    click AnalyzeHandler "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/handlers/analyze.go"
    click FileParser "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/services/file_parser.go"
    click AnalysisEngine "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/services/analysis_engine.go"
    click GeminiClient "https://github.com/hrshimpi/cf_ai_data-analyzer/blob/main/backend/services/gemini.go"
    click TempStorage "https://github.com/hrshimpi/cf_ai_data-analyzer/tree/main/storage/temp"
    click VertexAI "https://github.com/hrshimpi/cf_ai_data-analyzer/tree/main/N/A"

    %% Styles
    classDef client fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef component fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef page fill:#E6E6FA,stroke:#333,stroke-width:1px;
    classDef state fill:#FFE4B5,stroke:#333,stroke-width:1px;
    classDef api fill:#87CEFA,stroke:#333,stroke-width:1px;
    classDef service fill:#B0C4DE,stroke:#333,stroke-width:1px;
    classDef handler fill:#4682B4,stroke:#333,stroke-width:1px;
    classDef middleware fill:#5F9EA0,stroke:#333,stroke-width:1px;
    classDef storage fill:#98FB98,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px,shape:cloud;
```
