How harshturna/lynq works
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)