# srexrg/websight architecture

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

- Interactive diagram: https://gitdiagram.com/srexrg/websight
- Repository: https://github.com/srexrg/websight

## Overview

##### Project Type and Purpose
- Full-stack analytics dashboard built with Next.js 15 and TypeScript.
- Uses Supabase for database and authentication, Tailwind CSS/ShadCn for styling, Recharts and React Simple Maps for visuals, jsPDF for report export.

##### File-Structure Insights
- “app/” – Next.js App Router: top-level pages (/, /dashboard, /docs, /auth, /settings, /website/[domain]).
- “app/api/” – Backend API routes:
– auth/callback/route.ts (OAuth callback)
– events/route.ts (fetch analytics data)
– track/route.ts (receive tracking beacons)
- “public/tracker.js” – Standalone JS snippet injected into user’s sites to emit events.
- “components/” – React UI broken into subfolders: analytics, dashboard, landing, settings, auth, ui primitives.
- “lib/” & “utils/” – Shared business logic: database types, analytics utilities, CORS middleware, Supabase client/server wrappers, PDF export code.
- “utils/supabase/” – Encapsulates Supabase client initialization, server-side helpers, middleware for auth.
- Configs: next.config.ts, tsconfig.json, postcss.config.mjs, tailwind via globals.css.

##### Core Components and Their Relationships
– Browser/UI Layer
- Landing pages: marketing, quickstart, pricing
- Dashboard pages: real-time charts, custom events overview, world map
- Settings pages: domain management, code snippets
- Auth UI: login-button, sign-out-button components
- UI primitives: buttons, modals, accordions, charts, tooltips
– Tracking Script (public/tracker.js)
- Injected on user sites; captures pageviews/custom events and POSTs to Next.js /api/track
– Next.js Server (app/api/*)
- /api/track: validates CORS, forwards event data to Supabase via server helper
- /api/events: queries Supabase for aggregated metrics, returns JSON for charts
- /api/auth/callback: handles OAuth redirect from Supabase Auth
– Supabase
- Auth: user registration, sign-in via OAuth or email
- Database: event records, custom events schema, user-domain mappings
– External Libraries
- Recharts & React Simple Maps: rendering charts and world maps on client
- jsPDF: PDF report generation on client or server
- Framer Motion: UI animations

##### Architectural Patterns and Design Principles
- Monolithic Next.js app combining frontend and backend.
- App Router for nested layouts and server components.
- Separation of concerns:
– UI components in “components/”
– Business logic in “lib/” and “utils/”
– Data layer isolated via “utils/supabase/”
- API-first design: all data flows through defined REST endpoints.
- Event-driven tracking: client scripts fire events, server persists and aggregates them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser / End User"
        Landing["Landing & Marketing UI"]:::client
        Docs["Documentation UI"]:::client
        DashboardUI["Dashboard UI"]:::client
        Settings["Settings UI"]:::client
        AuthUI["Auth UI"]:::client
        WebsiteDetail["Website Detail UI"]:::client
        TrackingScript["Embedded Tracking Script"]:::client
    end

    subgraph "Next.js Application Server"
        AppRouter["App Router & Server Components"]:::server
        subgraph "API Layer"
            TrackAPI["/api/track"]:::server
            EventsAPI["/api/events"]:::server
            AuthCallback["/api/auth/callback"]:::server
        end
        CORS["CORS Middleware"]:::server
        SupaMiddleware["Supabase Auth Middleware"]:::server
        SupaClient["Supabase Client Init"]:::server
        SupaServer["Supabase Server Helpers"]:::server
    end

    subgraph "Supabase"
        AuthService["Auth Service"]:::db
        Database["PostgreSQL Database"]:::db
    end

    subgraph "Third-Party Libraries"
        Recharts["Recharts"]:::third
        Maps["React Simple Maps"]:::third
        jsPDFLib["jsPDF"]:::third
        Framer["Framer Motion"]:::third
    end

    %% Data Flows
    TrackingScript -->|"POST /api/track"| TrackAPI
    DashboardUI -->|"GET /api/events"| EventsAPI
    AuthUI -->|"OAuth login flow"| AuthCallback
    Settings -->|"OAuth login flow"| AuthCallback

    TrackAPI -->|"INSERT event"| SupaServer
    SupaServer --> Database

    EventsAPI -->|"SELECT metrics"| Database
    EventsAPI --> DashboardUI

    AuthCallback --> AuthService
    AuthService --> AuthCallback
    AuthCallback -->|"redirect"| AppRouter

    DashboardUI --> Recharts
    DashboardUI --> Maps
    DashboardUI --> Framer
    DashboardUI --> jsPDFLib

    %% UI navigation to server for page rendering
    Landing --> AppRouter
    Docs --> AppRouter
    Settings --> AppRouter
    WebsiteDetail --> AppRouter

    %% Click Events
    click Landing "https://github.com/srexrg/websight/blob/main/app/page.tsx"
    click Docs "https://github.com/srexrg/websight/tree/main/app/(root)/docs/"
    click DashboardUI "https://github.com/srexrg/websight/blob/main/app/(root)/dashboard/page.tsx"
    click Settings "https://github.com/srexrg/websight/blob/main/app/(root)/settings/page.tsx"
    click AuthUI "https://github.com/srexrg/websight/blob/main/app/(root)/auth/page.tsx"
    click WebsiteDetail "https://github.com/srexrg/websight/blob/main/app/(root)/website/[domain]/page.tsx"
    click TrackingScript "https://github.com/srexrg/websight/blob/main/public/tracker.js"
    click TrackAPI "https://github.com/srexrg/websight/blob/main/app/api/track/route.ts"
    click EventsAPI "https://github.com/srexrg/websight/blob/main/app/api/events/route.ts"
    click AuthCallback "https://github.com/srexrg/websight/blob/main/app/api/auth/callback/route.ts"
    click CORS "https://github.com/srexrg/websight/blob/main/utils/cors.ts"
    click SupaMiddleware "https://github.com/srexrg/websight/blob/main/utils/supabase/middleware.ts"
    click SupaClient "https://github.com/srexrg/websight/blob/main/utils/supabase/client.ts"
    click SupaServer "https://github.com/srexrg/websight/blob/main/utils/supabase/server.ts"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef server fill:#D4FDD4,stroke:#333,stroke-width:1px
    classDef db fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef third fill:#E0E0E0,stroke:#333,stroke-width:1px
```
