How rizzzky78/market-maven works
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