# harishivam/hage-ai architecture

> Architecture diagram of the GitHub repository harishivam/hage-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harishivam/hage-ai
- Repository: https://github.com/harishivam/hage-ai

## Overview

##### Project Type and Purpose
- This is a full‑stack, React‑based web application built with Next.js (app directory structure).
- Purpose: A dashboard (“Hage‑Ai”) that lets users sign up/login, upload CSV review data or paste social media text, and view sentiment analysis (charts, stats, history).

##### File Structure Analysis
- Top‑level “app” directory: Next.js app router for pages (dashboard, login, signup, global layout).
- “components” folder: UI components organized by feature (auth, dashboard, layout, theme) and a generic UI library.
- “hooks” and “lib”: Custom hooks and service code (e.g., `use-review-analysis`, `review-service.ts`) indicating a client⇄server data layer.
- Config files: `next.config.js`, `tailwind.config.ts`, `tsconfig.json`—typical for Next.js + TypeScript + Tailwind CSS.
- No internal “api” folder, so data operations likely go through external API endpoints (AI‑analysis service, auth provider).

##### Key Systems & Layers to Capture
a. Frontend (Browser)
- Next.js Client Components (e.g., forms, inputs, charts)
- Static assets (CSS, images, JS chunks) served from `.next/static`
b. Next.js Server
- Server Components and SSR/SSG rendering
- Build and caching layers (Webpack cache, manifest files under `.next/`)
- Routing (app folder routing → pages-manifest.json)
c. Data & Service Layer
- `review-service.ts` calls external API(s) for sentiment analysis
- Custom hooks (`use-review-analysis`, `use-review-filters`) abstract fetch logic
d. External Services
- AI/ML sentiment analysis API (e.g., OpenAI or proprietary service)
- Authentication provider (if used; could be OAuth or Auth0)
- File storage/hosting (e.g., S3) if CSV upload persists externally
e. Deployment & CDN
- Vercel (or similar) for hosting serverless Next.js functions and static assets
- CDN layer for caching static chunks and assets

##### Relationships & Data Flow
- User’s Browser ⇄ Next.js Server
- HTTP(S) GET/POST for pages and data APIs
- SSR Pages deliver HTML + JSON payloads
- Next.js Server → External Services
- review-service forwards CSV/text to AI API
- receives sentiment results → passes to client via props or next.js API routes
- Caching & Static Generation
- Static pages (login, signup) served from CDN
- Dynamic pages (dashboard) may use server-side rendering or incremental static regeneration

##### Architectural Patterns & Principles
- Component‑driven UI: reusable UI library under components/ui
- Separation of concerns:
- Presentation (components) vs Business logic (hooks, services) vs Utilities (lib/utils)
- SSR/SSG: Hybrid rendering strategies for performance
- Single codebase with clear folders for app, components, hooks, lib

##### Essential Elements
- Notes on rendering strategies (SSR vs static) if space allows

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer (Browser)"
        direction TB
        User["User Browser"]:::frontend
        subgraph "Next.js App Router Pages"
            direction TB
            DashboardPage["Dashboard Page"]:::frontend
            LoginPage["Login Page"]:::frontend
            SignupPage["Signup Page"]:::frontend
            GlobalLayout["Global Layout"]:::frontend
        end
        GlobalsCSS["Global CSS Stylesheet"]:::frontend
        subgraph "UI Components & Layout"
            direction TB
            AuthFormComp["Authentication Form"]:::frontend
            AuthFeatureForm["Auth Feature Wrapper"]:::frontend
            DashboardUI["Dashboard UI Components"]:::frontend
            LayoutComps["Layout Components"]:::frontend
            ThemeProvider["Theme Provider"]:::frontend
            ThemeToggle["Theme Toggle"]:::frontend
            UILib["Generic UI Library"]:::frontend
        end
        subgraph "Custom Hooks"
            direction TB
            ToastHook["use-toast"]:::frontend
            ReviewAnalysisHook["use-review-analysis"]:::frontend
            ReviewFiltersHook["use-review-filters"]:::frontend
        end

        User -->|"navigates"| DashboardPage
        User -->|"navigates"| LoginPage
        User -->|"navigates"| SignupPage
        DashboardPage -->|uses| GlobalLayout
        LoginPage -->|uses| GlobalLayout
        SignupPage -->|uses| GlobalLayout
        GlobalLayout -->|imports| GlobalsCSS
        GlobalLayout -->|renders| LayoutComps
        GlobalLayout -->|wraps| ThemeProvider
        ThemeProvider -->|toggles| ThemeToggle
        DashboardPage -->|renders| DashboardUI
        LoginPage -->|renders| AuthFormComp
        AuthFormComp -->|wraps| AuthFeatureForm
        DashboardUI -->|uses| UILib
        DashboardUI -->|uses| ReviewAnalysisHook
        DashboardUI -->|uses| ReviewFiltersHook
        AuthFormComp -->|uses| ToastHook
    end

    %% Server Layer
    subgraph "Server Layer (Next.js Server)"
        direction TB
        AppServer["Next.js App Server"]:::server
        ReviewService["Review Service Module"]:::server
        Utils["Utility Functions"]:::server
        Types["Review Data Types"]:::server
        BuildCache["Build & Cache (.next/)"]:::server
    end

    DashboardPage -->|SSR/SSG request| AppServer
    AppServer -->|calls| ReviewService
    ReviewService -->|imports| Utils
    ReviewService -->|imports| Types
    AppServer -->|serves| BuildCache

    %% CDN / Static Assets
    .nextStatic["Static Assets (.next/static/)"]:::cdn
    BuildCache -->|deploy static| .nextStatic
    User -->|fetches| .nextStatic

    %% External Services
    subgraph "External Services"
        direction TB
        AIAPI["AI/ML Sentiment API"]:::external
        AuthProvider["Authentication Provider"]:::external
        FileStorage["File Storage (S3)"]:::external
    end

    ReviewService -->|forwards data| AIAPI
    AuthFeatureForm -.->|auth calls| AuthProvider
    ReviewService -->|uploads CSV| FileStorage

    %% Click Events
    click DashboardPage "https://github.com/harishivam/hage-ai/blob/main/app/dashboard/page.tsx"
    click LoginPage "https://github.com/harishivam/hage-ai/blob/main/app/login/page.tsx"
    click SignupPage "https://github.com/harishivam/hage-ai/blob/main/app/signup/page.tsx"
    click GlobalLayout "https://github.com/harishivam/hage-ai/blob/main/app/layout.tsx"
    click GlobalsCSS "https://github.com/harishivam/hage-ai/blob/main/app/globals.css"
    click AuthFormComp "https://github.com/harishivam/hage-ai/blob/main/components/auth/auth-form.tsx"
    click AuthFeatureForm "https://github.com/harishivam/hage-ai/blob/main/lib/features/auth/auth-form.tsx"
    click DashboardUI "https://github.com/harishivam/hage-ai/tree/main/components/dashboard/"
    click LayoutComps "https://github.com/harishivam/hage-ai/tree/main/components/layout/"
    click ThemeProvider "https://github.com/harishivam/hage-ai/blob/main/components/theme-provider.tsx"
    click ThemeToggle "https://github.com/harishivam/hage-ai/blob/main/components/theme/theme-toggle.tsx"
    click UILib "https://github.com/harishivam/hage-ai/tree/main/components/ui/"
    click ToastHook "https://github.com/harishivam/hage-ai/blob/main/hooks/use-toast.ts"
    click ReviewAnalysisHook "https://github.com/harishivam/hage-ai/blob/main/lib/hooks/use-review-analysis.ts"
    click ReviewFiltersHook "https://github.com/harishivam/hage-ai/blob/main/lib/hooks/use-review-filters.ts"
    click ReviewService "https://github.com/harishivam/hage-ai/blob/main/lib/services/review-service.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef server fill:#D6FFD6,stroke:#28a745,color:#000
    classDef external fill:#FFE0B2,stroke:#ff8c00,color:#000
    classDef cdn fill:#FFF59D,stroke:#f1c40f,color:#000
```
