# mendableai/firegeo architecture

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

- Interactive diagram: https://gitdiagram.com/mendableai/firegeo
- Repository: https://github.com/mendableai/firegeo

## Overview

##### Project type and purpose
- This is a full-stack SaaS starter application built with Next.js 15, TypeScript, Tailwind CSS, and PostgreSQL.
- It provides user authentication (Better Auth), billing (Autumn + Stripe), AI-powered chat, brand monitoring (using Firecrawl and multiple AI providers), email notifications (Resend), and a Postgres database accessed via Drizzle ORM.

##### File structure
- **app/**: Next.js 15 “app directory” containing both page components and serverless API routes under app/api.
- app/api/auth, app/api/autumn, app/api/brand-monitor, app/api/chat, app/api/credits, app/api/user – These route.ts files implement RESTful or RPC endpoints.
- app/(auth) and other page folders: client-side pages (login, register, dashboard, brand-monitor UI, chat UI, pricing, etc.).
- **components/**: React UI components split by feature (autumn, brand-monitor, ui).
- **lib/**: Shared utilities, API wrappers, database client & schema (lib/db), provider configs, SSE parser, scraping helpers, error types.
- **hooks/**: React hooks for data fetching and subscriptions (useConversations, useBrandAnalyses, useAutumnCustomer, etc.).
- **config/**: Static configuration (autumn-products, constants).
- **migrations** & **better-auth_migrations**: SQL migration files for Drizzle ORM and Better Auth.
- **scripts/**: Setup scripts (Autumn billing, Stripe portal).
- **middleware.ts**, **next.config.ts**: Next.js configuration.

##### README for additional insights
- Confirms tech stack: Next.js, React, Tailwind CSS, Drizzle ORM, Better Auth, Autumn, Firecrawl, AI providers, Resend.
- Lists project structure and setup workflow.

a. Main components:
1. Client Browser – React SPA pages served by Next.js
2. Next.js Server (Edge or Node Serverless Lambdas)
- SSR pages
- API routes under app/api/**
3. Authentication Service – Better Auth
4. Billing Service – Autumn (Stripe integration)
5. Database – PostgreSQL (Drizzle ORM)
6. AI Providers – OpenAI, Anthropic, Google Gemini, Perplexity
7. Web⁠-Scraping Service – Firecrawl
8. Email Service – Resend
9. SSE/Event Stream – Server-Sent Events for long-polling in brand-monitor
b. Relationships & data flows:
- Browser ←→ Next.js pages (HTTP/HTTPS).
- Browser → Next.js API (fetch calls from hooks like useMessages, useBrandAnalyses).
- Next.js API ↔ Database (lib/db.ts via Drizzle ORM).
- Next.js API ↔ Better Auth for session, JWT, user management.
- Next.js API ↔ Autumn billing endpoints for subscription, usage tracking.
- Next.js API ↔ Firecrawl & AI providers for brand analysis and chat.
- Next.js API ↔ Resend email service.
- SSE connections from API (app/api/brand-monitor/hooks/use-sse-handler.ts) → Browser for real-time updates.
c. Architectural patterns/design principles:
- Folder-based routing & API routes (Next.js app router).
- Serverless functions for each API route.
- Layered architecture: UI components, data-fetching hooks, API services, business logic in lib/, persistence layer in lib/db.
- Single source of configuration (config/, env-validation).
- Event streaming for long-polling / real-time device updates.
d. Key technologies & libraries:
- Next.js 15 (app router + serverless routes)
- React 19 + TypeScript 5.7
- Tailwind CSS & shadcn/ui
- Drizzle ORM + PostgreSQL
- Better Auth (authentication & migrations)
- Autumn + Stripe (billing)
- Firecrawl (web scraping)
- OpenAI, Anthropic, Google Gemini, Perplexity (AI chat & brand analysis)
- Resend (email)
- SSE parser & utilities for real-time streams

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        PagesGroup["Next.js Pages"]:::internal
        LB["Layout"]:::internal
        PH["Home Page"]:::internal
        LG["Login Page"]:::internal
        RG["Register Page"]:::internal
        FP["Forgot Password"]:::internal
        RP["Reset Password"]:::internal
        DBP["Dashboard Page"]:::internal
        BMP["Brand Monitor Page"]:::internal
        CP["Chat Page"]:::internal
        PL["Plans Page"]:::internal
        PDP["Dynamic Pricing Page"]:::internal
        PPP["Public Pricing Page"]:::internal
        AVP["Autumn Verify Page"]:::internal

        LB --> PagesGroup
        PH --> PagesGroup
        LG --> PagesGroup
        RG --> PagesGroup
        FP --> PagesGroup
        RP --> PagesGroup
        DBP --> PagesGroup
        BMP --> PagesGroup
        CP --> PagesGroup
        PL --> PagesGroup
        PDP --> PagesGroup
        PPP --> PagesGroup
        AVP --> PagesGroup
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        direction TB
        APIGroup["Next.js API Routes"]:::internal
        AuthAll["Auth [...all]"]:::internal
        AuthDebug["Auth Debug"]:::internal
        AuthSession["Auth Session"]:::internal
        AuthTestDB["Auth Test-DB"]:::internal
        AutumnAll["Autumn [...all]"]:::internal
        BMAnalyze["Brand-Monitor Analyze"]:::internal
        BMScrape["Brand-Monitor Scrape"]:::internal
        BMBatch["Brand-Monitor Batch Scrape"]:::internal
        BMCheckProv["Brand-Monitor Check Providers"]:::internal
        BMWebSearch["Brand-Monitor Web-Search"]:::internal
        BMAnalyses["Brand-Monitor Analyses"]:::internal
        BMAnalysisDetail["Brand-Monitor Analysis Detail"]:::internal
        ChatRoot["Chat"]:::internal
        ChatConv["Chat Conversation"]:::internal
        ChatFB["Chat Feedback"]:::internal
        Credits["Credits"]:::internal
        UserProfile["User Profile"]:::internal
        UserSettings["User Settings"]:::internal

        AuthAll --> APIGroup
        AuthDebug --> APIGroup
        AuthSession --> APIGroup
        AuthTestDB --> APIGroup
        AutumnAll --> APIGroup
        BMAnalyze --> APIGroup
        BMScrape --> APIGroup
        BMBatch --> APIGroup
        BMCheckProv --> APIGroup
        BMWebSearch --> APIGroup
        BMAnalyses --> APIGroup
        BMAnalysisDetail --> APIGroup
        ChatRoot --> APIGroup
        ChatConv --> APIGroup
        ChatFB --> APIGroup
        Credits --> APIGroup
        UserProfile --> APIGroup
        UserSettings --> APIGroup
    end

    %% Data & Integrations Layer
    subgraph "Data & Integrations" 
        direction TB
        DB["PostgreSQL (Drizzle ORM)"]:::db
        AUTH["Better Auth"]:::external
        BILL["Autumn/Stripe Billing"]:::external
        AI["AI Providers"]:::external
        SCRAPE["Firecrawl"]:::external
        EMAIL["Resend Email"]:::external
        SSE["SSE/Event Stream"]:::external
    end

    %% Connections
    PagesGroup -->|"fetch calls"| APIGroup
    APIGroup -->|"queries"| DB
    APIGroup -->|"auth requests"| AUTH
    APIGroup -->|"billing requests"| BILL
    APIGroup -->|"AI calls"| AI
    APIGroup -->|"scraping requests"| SCRAPE
    APIGroup -->|"send emails"| EMAIL
    APIGroup -->|"SSE stream"| SSE

    %% Click Events - Frontend Pages
    click LB "https://github.com/mendableai/firegeo/blob/main/app/layout.tsx"
    click PH "https://github.com/mendableai/firegeo/blob/main/app/page.tsx"
    click LG "https://github.com/mendableai/firegeo/blob/main/app/login/page.tsx"
    click RG "https://github.com/mendableai/firegeo/blob/main/app/register/page.tsx"
    click FP "https://github.com/mendableai/firegeo/blob/main/app/forgot-password/page.tsx"
    click RP "https://github.com/mendableai/firegeo/blob/main/app/reset-password/page.tsx"
    click DBP "https://github.com/mendableai/firegeo/blob/main/app/dashboard/page.tsx"
    click BMP "https://github.com/mendableai/firegeo/blob/main/app/brand-monitor/page.tsx"
    click CP "https://github.com/mendableai/firegeo/blob/main/app/chat/page.tsx"
    click PL "https://github.com/mendableai/firegeo/blob/main/app/plans/page.tsx"
    click PDP "https://github.com/mendableai/firegeo/blob/main/app/pricing-dynamic/page.tsx"
    click PPP "https://github.com/mendableai/firegeo/blob/main/app/pricing-public/page.tsx"
    click AVP "https://github.com/mendableai/firegeo/blob/main/app/autumn-verify/page.tsx"

    %% Click Events - API Routes
    click AuthAll "https://github.com/mendableai/firegeo/blob/main/app/api/auth/[...all]/route.ts"
    click AuthDebug "https://github.com/mendableai/firegeo/blob/main/app/api/auth/debug/route.ts"
    click AuthSession "https://github.com/mendableai/firegeo/blob/main/app/api/auth/session/route.ts"
    click AuthTestDB "https://github.com/mendableai/firegeo/blob/main/app/api/auth/test-db/route.ts"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/app/api/autumn/[...all]/route.ts"
    click BMAnalyze "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/analyze/route.ts"
    click BMScrape "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/scrape/route.ts"
    click BMBatch "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/batch-scrape/route.ts"
    click BMCheckProv "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/check-providers/route.ts"
    click BMWebSearch "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/web-search/route.ts"
    click BMAnalyses "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/analyses/route.ts"
    click BMAnalysisDetail "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/analyses/[analysisId]/route.ts"
    click ChatRoot "https://github.com/mendableai/firegeo/blob/main/app/api/chat/route.ts"
    click ChatConv "https://github.com/mendableai/firegeo/blob/main/app/api/chat/[conversationId]/route.ts"
    click ChatFB "https://github.com/mendableai/firegeo/blob/main/app/api/chat/feedback/route.ts"
    click Credits "https://github.com/mendableai/firegeo/blob/main/app/api/credits/route.ts"
    click UserProfile "https://github.com/mendableai/firegeo/blob/main/app/api/user/profile/route.ts"
    click UserSettings "https://github.com/mendableai/firegeo/blob/main/app/api/user/settings/route.ts"

    %% Click Events - Auth Service
    click AUTH "https://github.com/mendableai/firegeo/blob/main/better-auth.config.ts"
    click AUTH "https://github.com/mendableai/firegeo/blob/main/better-auth_migrations/initial-schema.sql"
    click AuthAll "https://github.com/mendableai/firegeo/blob/main/lib/auth.ts"
    click AuthAll "https://github.com/mendableai/firegeo/blob/main/lib/auth-client.ts"

    %% Click Events - Billing Service
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/components/autumn/attach-dialog.tsx"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/components/autumn/pricing-table.tsx"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/components/autumn/product-change-dialog.tsx"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/lib/autumn/attach-content.tsx"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/lib/autumn/pricing-table-content.tsx"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/config/autumn-products.ts"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/scripts/setup-autumn.ts"
    click AutumnAll "https://github.com/mendableai/firegeo/blob/main/scripts/setup-stripe-portal.ts"

    %% Click Events - Database
    click DB "https://github.com/mendableai/firegeo/blob/main/drizzle.config.ts"
    click DB "https://github.com/mendableai/firegeo/blob/main/lib/db.ts"
    click DB "https://github.com/mendableai/firegeo/blob/main/lib/db/schema.ts"
    click DB "https://github.com/mendableai/firegeo/blob/main/lib/db/index.ts"
    click DB "https://github.com/mendableai/firegeo/blob/main/migrations/001_create_app_schema.sql"
    click DB "https://github.com/mendableai/firegeo/blob/main/migrations/README.md"
    click DB "https://github.com/mendableai/firegeo/blob/main/better-auth_migrations/initial-schema.sql"

    %% Click Events - AI Providers
    click AI "https://github.com/mendableai/firegeo/blob/main/lib/ai-utils.ts"
    click AI "https://github.com/mendableai/firegeo/blob/main/lib/ai-utils-enhanced.ts"
    click AI "https://github.com/mendableai/firegeo/blob/main/lib/anthropic-web-search.ts"
    click AI "https://github.com/mendableai/firegeo/blob/main/lib/providers/query-provider.tsx"
    click AI "https://github.com/mendableai/firegeo/blob/main/lib/provider-config.ts"
    click AI "https://github.com/mendableai/firegeo/blob/main/config/constants.ts"

    %% Click Events - Web-Scraping
    click SCRAPE "https://github.com/mendableai/firegeo/blob/main/lib/scrape-utils.ts"
    click BMScrape "https://github.com/mendableai/firegeo/blob/main/app/api/brand-monitor/scrape/route.ts"

    %% Click Events - Email Service
    click EMAIL "https://github.com/mendableai/firegeo/blob/main/lib/email.ts"

    %% Click Events - SSE/Event Stream
    click SSE "https://github.com/mendableai/firegeo/blob/main/lib/sse-parser.ts"
    click SSE "https://github.com/mendableai/firegeo/blob/main/components/brand-monitor/hooks/use-sse-handler.ts"

    %% Styles
    classDef internal fill:#daf5d9,stroke:#2f7d32,stroke-width:1px
    classDef db fill:#d9eaf5,stroke:#1e4f91,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#b35900,stroke-width:1px
```
