# harshturna/lynq architecture

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

- Interactive diagram: https://gitdiagram.com/harshturna/lynq
- Repository: https://github.com/harshturna/lynq

## Overview

##### Project type and purpose
- Lynq is a full-stack web application built with Next.js (React + TypeScript) that provides privacy-first web analytics and performance monitoring.
- It ingests tracking data (via a separate JS script), stores and processes it in Supabase, and presents dashboards to end users.

##### File structure
- Top-level “app” folder follows Next.js’s App Router:
- auth routes: /login, /sign-up
- landing routes: marketing pages under (landing)
- main routes: authenticated dashboard and per-website views under (main)
- API routes: app/api/lynq/route.ts (data ingestion endpoint)
- “components” and “components/ui” hold reusable React UI elements.
- “lib” holds abstractions for Supabase client/server logic, user management, and utils.
- “hooks” contains custom React hooks.
- Configs and assets: tailwind, postcss, tsconfig, public/assets, next.config.mjs.
- Middleware (middleware.ts) may handle auth checks or routing rules.

##### Key insights from README
- Core features: real-time visitor tracking, custom events, performance monitoring, privacy controls.
- Data flow: front-end tracker → ingestion API → Supabase DB → dashboard queries.
- External script repo (“lynq-js”) pushes events to the Next.js API.

##### Components
a. Frontend:
- Public landing pages (marketing)
- Auth pages (login/signup with Supabase Auth)
- User dashboard (Next.js SSR/CSR pages under (main))
- Third-party tracker script (hosted separately or via CDN)
b. API Layer:
- Next.js API route (/api/lynq)
- Middleware for auth & data validation
c. Backend Services:
- Supabase Auth & Database (PostgreSQL + real-time)
- Supabase Edge Functions (if used)
d. External Dependencies:
- CDN for static assets & tracker script
- Optional email/SMS services (if part of signup flows)

##### Relationships & Data Flow
- Visitor’s browser loads tracker script → script captures events → POST to /api/lynq
- Next.js API validates/authenticates (if needed) → writes raw events to Supabase
- Dashboard pages fetch aggregated metrics via server-side data fetching from Supabase
- Realtime or scheduled functions may process/aggregate raw events into summary tables

##### Architectural patterns & design principles
- Jamstack / Serverless style: Next.js renders pages + hosts API routes as serverless functions
- Separation of concerns:
- UI components under “components/ui”
- Business logic under “lib”
- Routing & layout under “app”
- Incremental Static Regeneration (ISR) or SSR for dashboards
- Privacy by design: data anonymization in ingestion layer

##### Technologies & frameworks to annotate
- Next.js App Router, React, TypeScript, Tailwind CSS
- Supabase (Auth, Postgres, Realtime)
- Vercel or similar for deployment (serverless functions + CDN)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services" 
        direction TB
        CDN["CDN (Static Assets & Tracker Script)"]:::external
        TrackerScript["lynq-js Tracker Script"]:::external
        EmailService["Email/SMS Service"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        Browser["User Browser"]:::frontend
        subgraph "Public Landing Pages"
            LandingPages["Landing Pages"]:::frontend
        end
        subgraph "Auth Pages"
            LoginPage["Login Page"]:::frontend
            SignUpPage["Sign-Up Page"]:::frontend
            AuthActions["Auth Actions"]:::frontend
        end
        subgraph "Main Dashboard"
            DashboardOverview["Dashboard Overview"]:::frontend
            DashboardWidgets["Dashboard Widgets"]:::frontend
            WebsitePage["Website Analytics Page"]:::frontend
            WebsiteComponents["Website Analytics Components"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer (Serverless Functions)"
        direction TB
        Middleware["Global Middleware"]:::backend
        SupaMiddleware["Supabase Middleware Helpers"]:::backend
        APIIngestion["/api/lynq Ingestion API"]:::backend
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        AuthDB["Supabase Auth"]:::backend
        PostgresDB["Supabase PostgreSQL & Realtime"]:::backend
        EdgeFunctions["Supabase Edge Functions"]:::backend
    end

    %% Libraries & Utils
    subgraph "Lib & Business Logic"
        direction TB
        SupaClient["Supabase Client Init"]:::backend
        SupaServer["Supabase Server Utils"]:::backend
        UserClient["User Helpers (Client)"]:::backend
        UserServer["User Helpers (Server)"]:::backend
        Actions["General Actions"]:::backend
        Utils["Utility Functions"]:::backend
    end

    %% UI Components
    subgraph "UI Components"
        direction TB
        GenericUI["components/ui/*"]:::frontend
        Header["Header"]:::frontend
        Footer["Footer"]:::frontend
        Loading["Loading"]:::frontend
    end

    %% Data Flow
    Browser -->|"loads from CDN"| TrackerScript
    TrackerScript -->|"HTTP POST /api/lynq"| APIIngestion
    APIIngestion -->|writes raw events| PostgresDB
    APIIngestion -->|auth checks| AuthDB
    APIIngestion -->|calls middleware| Middleware
    Middleware --> SupaMiddleware

    DashboardOverview -->|"SSR/CSR fetch"| PostgresDB
    WebsitePage -->|"fetch metrics"| PostgresDB
    DashboardOverview -->|"uses client utils"| SupaClient
    WebsitePage -->|"uses server utils"| SupaServer

    LoginPage -->|uses Supabase Auth| AuthDB
    SignUpPage -->|triggers email| EmailService

    CDN --> Browser

    %% Click Events
    click LandingPages "https://github.com/harshturna/lynq/blob/main/app/(landing)/page.tsx"
    click LoginPage "https://github.com/harshturna/lynq/blob/main/app/(auth)/login/page.tsx"
    click SignUpPage "https://github.com/harshturna/lynq/blob/main/app/(auth)/sign-up/page.tsx"
    click AuthActions "https://github.com/harshturna/lynq/blob/main/app/(auth)/actions.ts"
    click DashboardOverview "https://github.com/harshturna/lynq/blob/main/app/(main)/dashboard/page.tsx"
    click DashboardWidgets "https://github.com/harshturna/lynq/tree/main/app/(main)/dashboard/_components/*"
    click WebsitePage "https://github.com/harshturna/lynq/blob/main/app/(main)/[website_slug]/page.tsx"
    click WebsiteComponents "https://github.com/harshturna/lynq/tree/main/app/(main)/[website_slug]/_components/*"
    click APIIngestion "https://github.com/harshturna/lynq/blob/main/app/api/lynq/route.ts"
    click Middleware "https://github.com/harshturna/lynq/blob/main/middleware.ts"
    click SupaMiddleware "https://github.com/harshturna/lynq/blob/main/lib/supabase/middleware.ts"
    click SupaClient "https://github.com/harshturna/lynq/blob/main/lib/supabase/client.ts"
    click SupaServer "https://github.com/harshturna/lynq/blob/main/lib/supabase/server.ts"
    click UserClient "https://github.com/harshturna/lynq/blob/main/lib/user/client.ts"
    click UserServer "https://github.com/harshturna/lynq/blob/main/lib/user/server.ts"
    click Actions "https://github.com/harshturna/lynq/blob/main/lib/actions.ts"
    click Utils "https://github.com/harshturna/lynq/blob/main/lib/utils.ts"
    click GenericUI "https://github.com/harshturna/lynq/tree/main/components/ui/*"
    click Header "https://github.com/harshturna/lynq/blob/main/components/header.tsx"
    click Footer "https://github.com/harshturna/lynq/blob/main/components/footer.tsx"
    click Loading "https://github.com/harshturna/lynq/blob/main/components/loading.tsx"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
