# rizzzky78/market-maven architecture

> Architecture diagram of the GitHub repository rizzzky78/market-maven, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rizzzky78/market-maven
- Repository: https://github.com/rizzzky78/market-maven

## Overview

##### Main High-Level Components
- User Interface (Next.js Frontend)
- Pages & UI components under src/app and src/components
- Chat interface, navigation, product cards, forms
- Serverless Backend (Next.js API Routes & Orchestrator)
- src/app/api/** routes group (public analytics, markdown-store, object-store, tool-data-store, auth, blur-data-url, ratings)
- Orchestrator logic inside lib/agents/action/chat-service and lib/agents/action/mutator
- Agent Tools
- recommendator, searchProduct, getProductDetails, productsComparison, inquireUser
- Implemented under lib/agents/tools/api and invoked by the orchestrator
- External Services
- AI Providers: Google Generative AI (Gemini), Groq, xAI, DeepSeek
- Web Scraper: Firecrawl
- Search APIs: Tavily, Serper
- Authentication Providers: GitHub, Google via NextAuth.js
- Data Stores
- Upstash Redis (cache, session) – accessed via lib/service/cache-store and NextAuth.js adapter
- Neon PostgreSQL (persistent tables: scrape_cache, markdown_store, object_store, tool_data_store, shares) – accessed via src/database/neon and lib/service/store
- Static Assets
- public/ folder (markdown examples, snapshots, videos, static JSON)

##### Component Relationships & Data Flow
- User interacts with the Next.js UI (browser)
→ Frontend calls API routes (fetch) or uses React Server Components
- API route (e.g., /api/store/tool-data-store) forwards request to the Orchestrator
→ Orchestrator (lib/agents/action/chat-service) analyzes intent
→ Selects appropriate tool module (lib/agents/tools/api or lib/agents/action/mutator)
- Tool executes:
→ May call Firecrawl (web scraping)
→ May call external API (Tavily, Serper)
→ May call AI model (Gemini, Groq, etc.) via unified AI client in lib/agents/schema or lib/utility/provider/ai-state-provider
- Results streaming:
→ Mutator updates AI/UI state (lib/agents/action/mutator)
→ Writes intermediate or final data to Redis (cache-store) or PostgreSQL (store)
→ Frontend receives streamed chunks (React Server Components, ai/rsc) and renders messages or tables
- Authentication & Session:
→ NextAuth.js (src/app/api/auth) manages OAuth flows, sessions stored in Redis or DB
- Analytics & Sharing:
→ Public analytics endpoint logs to service/share-analytics
→ Share endpoints generate shareable links, record to “shares” table

##### Architectural Patterns & Principles
- Separation of Concerns
- UI layer vs. API layer vs. core orchestration vs. data layer
- Serverless Functions
- Next.js App Router’s route handlers for on-demand scaling
- Streaming Data Flow
- AI responses streamed via React Server Components (ai/rsc)
- Modular Agent Framework
- Each tool is a self-contained module with schema validation
- Caching & Persistence
- Query cache (Redis) to avoid redundant scraping
- Persistent audit logs in PostgreSQL

a. Left side: User → Browser (Next.js React UI)
b. Middle tier:
- API Gateway (Next.js API Routes)
- Orchestrator Module
- Agent Tool Modules (branching paths)
c. Right side: External Services (AI Providers, Firecrawl, Tavily, Serper)
d. Bottom: Data Stores (Redis cache, PostgreSQL tables)
e. Side: Auth Service (NextAuth.js OAuth providers) & Analytics/Share service

## Diagram (Mermaid)

```mermaid
flowchart TB
    User((User)):::user

    subgraph "Frontend (Next.js UI)"
        UI1["Browser (React UI)"]:::frontend
        UI2["src/app"]:::frontend
        UI3["src/components"]:::frontend
    end

    subgraph "Serverless Backend (API Routes)"
        Analytics["/api/public/analytics"]:::api
        Share["/api/public/share"]:::api
        MDStore["/api/store/markdown-store"]:::api
        ObjStore["/api/store/object-store"]:::api
        ToolData["/api/store/tool-data-store"]:::api
        Blur["/api/blur-data-url"]:::api
        Ratings["/api/ratings"]:::api
        AuthRoute["/api/auth/[...nextauth]"]:::api
    end

    subgraph "Orchestrator (Core Logic)"
        ChatService["Chat Service"]:::core
        RateLimit["Rate Limit Middleware"]:::core
        Mutator["Mutator (AI State Service)"]:::core
    end

    subgraph "Agent Tools"
        Firecrawl["Firecrawl"]:::external
        Serper["Serper"]:::external
        Tavily["Tavily"]:::external
    end

    AIClient["Unified AI Client"]:::external

    subgraph "Data Stores"
        Redis[(Redis Cache)]:::db
        Postgres[(PostgreSQL)]:::db
    end

    subgraph "Analytics & Sharing Services"
        ShareAnal["Share Analytics Service"]:::core
        ShareService["Share Service"]:::core
    end

    subgraph "Static Assets"
        Static1["public/markdown"]:::assets
        Static2["public/vid"]:::assets
        Static3["public/snapshots"]:::assets
    end

    User --> UI1
    UI1 --> UI2
    UI2 --> UI3

    UI3 --> Analytics
    UI3 --> Share
    UI3 --> MDStore
    UI3 --> ObjStore
    UI3 --> ToolData
    UI3 --> Blur
    UI3 --> Ratings
    UI3 --> AuthRoute

    Analytics --> ShareAnal
    Share --> ShareService

    Analytics --> ShareAnal
    Share --> ShareService

    MDStore --> ChatService
    ObjStore --> ChatService
    ToolData --> ChatService
    Blur --> ChatService
    Ratings --> ChatService
    AuthRoute --> ChatService

    ChatService --> RateLimit
    RateLimit --> ChatService
    ChatService --> Mutator

    ChatService --> Firecrawl
    ChatService --> Serper
    ChatService --> Tavily
    ChatService --> AIClient

    Mutator --> Redis
    Mutator --> Postgres

    AuthRoute --> Redis
    AuthRoute --> Postgres

    ShareAnal --> Postgres
    ShareService --> Postgres

    Static1 --> UI2
    Static2 --> UI2
    Static3 --> UI2

    click UI2 "https://github.com/rizzzky78/market-maven/tree/main/src/app"
    click UI3 "https://github.com/rizzzky78/market-maven/tree/main/src/components"
    click Analytics "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/(public)/analytics/route.ts"
    click Share "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/(public)/share/route.ts"
    click MDStore "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/(store)/markdown-store/route.ts"
    click ObjStore "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/(store)/object-store/route.ts"
    click ToolData "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/(store)/tool-data-store/route.ts"
    click Blur "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/blur-data-url/route.ts"
    click Ratings "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/ratings/route.ts"
    click AuthRoute "https://github.com/rizzzky78/market-maven/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click ChatService "https://github.com/rizzzky78/market-maven/blob/main/src/lib/agents/action/chat-service/index.ts"
    click RateLimit "https://github.com/rizzzky78/market-maven/blob/main/src/lib/agents/action/chat-service/rate-limit-middleware.ts"
    click Mutator "https://github.com/rizzzky78/market-maven/blob/main/src/lib/agents/action/mutator/ai-state-service.ts"
    click Firecrawl "https://github.com/rizzzky78/market-maven/blob/main/src/lib/agents/tools/api/firecrawl.ts"
    click Serper "https://github.com/rizzzky78/market-maven/blob/main/src/lib/agents/tools/api/serper.ts"
    click Tavily "https://github.com/rizzzky78/market-maven/blob/main/src/lib/agents/tools/api/tavily.ts"
    click AIClient "https://github.com/rizzzky78/market-maven/blob/main/src/lib/utility/provider/ai-state-provider.tsx"
    click Redis "https://github.com/rizzzky78/market-maven/blob/main/src/database/redis/index.ts"
    click Postgres "https://github.com/rizzzky78/market-maven/blob/main/src/database/neon/index.ts"
    click ShareAnal "https://github.com/rizzzky78/market-maven/blob/main/src/lib/service/share-analytics.ts"
    click ShareService "https://github.com/rizzzky78/market-maven/blob/main/src/lib/service/share.ts"
    click Static1 "https://github.com/rizzzky78/market-maven/tree/main/public/markdown"
    click Static2 "https://github.com/rizzzky78/market-maven/tree/main/public/vid"
    click Static3 "https://github.com/rizzzky78/market-maven/tree/main/public/snapshots"

    classDef frontend fill:#ADD8E6,stroke:#000
    classDef api fill:#ADD8E6,stroke:#000
    classDef core fill:#98FB98,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef db fill:#DDA0DD,stroke:#000
    classDef assets fill:#D3D3D3,stroke:#000
    classDef user fill:#FFFFFF,stroke:#000,line-width:2px
```
