Hector Analytics Development

Expert assistance for developing Hector Analytics, a privacy-first web analytics SaaS platform that provides a cookieless alternative to Google Analytics.

Project Context

Hector Analytics is built with Next.js App Router, Supabase (PostgreSQL), shadcn/ui components, and Tailwind CSS v4. The platform emphasizes privacy-first analytics without cookies, featuring IP geolocation, real-time session tracking, and comprehensive dashboard visualizations.

Development Workflow

Essential Commands

When working with this project, use these commands:

1. **Start development server**: Run `pnpm dev` to start the Next.js development server with Turbopack on http://localhost:3000

2. **Build production**: Run `pnpm build` to create a production-optimized build

3. **Start production server**: Run `pnpm start` to run the production build locally

4. **Lint code**: Run `pnpm lint` to check code quality with ESLint

Environment Setup

Always verify these environment variables exist in `.env.local`:

Architecture Guidelines

Project Structure

The codebase follows this structure:

- `api/track/` - Analytics tracking endpoint

- `auth/` - Authentication flows (sign-in, sign-up, callback)

- `dashboard/[domain]/` - Domain-specific analytics dashboards

- Marketing pages at root level

- `ui/` - shadcn/ui reusable components

- `SiteData/` - Analytics visualization components

- `auth-*.tsx` - Authentication form components

- `supabase/` - Supabase client configurations

- `geo.ts` - IP geolocation utilities

Supabase Client Pattern

CRITICAL: Use the correct Supabase client for each context:

1. **Server Components & Route Handlers**: Use `createClient()` from `lib/supabase/server.ts`

2. **Client Components**: Use `createClient()` from `lib/supabase/client.ts`

3. **Admin Operations**: Use `createAdminClient()` from `lib/supabase/admin.ts` (requires service role key)

Never mix client types - this will cause authentication and data access issues.

Authentication Implementation

Follow these authentication patterns:

Analytics Tracking Architecture

The privacy-first analytics system works as follows:

1. Website owners embed `/public/script.js` on their sites

2. The script sends pageview data to `/api/track` endpoint

3. No cookies are set - tracking uses sessions stored in database

4. IP geolocation via MaxMind GeoIP2 adds country/city data

5. Sessions table stores: visitor sessions, paths, referrers, devices, locations

6. Dashboard components (`SiteData/`) visualize the analytics data

Database Schema

Key tables in Supabase:

Component Development

UI Component Guidelines

When creating or modifying components:

1. Use shadcn/ui patterns from `components/ui/` directory

2. All components must be TypeScript with proper type definitions

3. Use `cn()` utility from `lib/utils.ts` for className merging

4. Forms should use React Hook Form with Zod validation schemas

5. Follow existing component patterns for consistency

Styling Guidelines

Apply styles using these conventions:

1. Tailwind CSS v4 with CSS-first configuration in `app/globals.css`

2. Theme variables are CSS custom properties (see `globals.css`)

3. Support dark/light mode via next-themes

4. Primary brand color is `#3d9dbd` (blue)

5. Use semantic color tokens (e.g., `bg-background`, `text-foreground`)

Code Quality Standards

TypeScript

Best Practices

Common Tasks

Adding a New Analytics Visualization

1. Create component in `components/SiteData/`

2. Fetch data using Supabase server client in Server Component

3. Pass data to Client Component for interactivity if needed

4. Use existing chart patterns from other SiteData components

5. Add to dashboard page at `app/dashboard/[domain]/page.tsx`

Adding Authentication to New Routes

1. Add route pattern to middleware configuration

2. Use `getUser()` from Supabase server client to verify auth

3. Redirect to `/auth/sign-in` if unauthenticated

4. Access user data via session in protected routes

Creating New API Endpoints

1. Add route handler in `app/api/[endpoint]/route.ts`

2. Use appropriate Supabase client (server or admin)

3. Validate request data with Zod schemas

4. Return proper HTTP status codes and JSON responses

5. Handle errors gracefully with try-catch blocks

Troubleshooting

Common Issues

Additional Notes

This is a SaaS application following modern Next.js best practices. Always consider: