WorkTrace

Browser extension + web dashboard that captures developer session context and generates AI-powered session reports.

What it is

A Chrome extension (Manifest V3) silently records the pages a developer opens during a coding session — URLs, titles, page metadata, tags, optionally the music they listen to — and ships them to a Next.js dashboard. The dashboard renders a per-session timeline and asks an LLM to summarize each session into a structured Markdown report.

See docs/Task.md for the full specification, acceptance criteria, and four-week roadmap.

Repo layout

worktrace/
├─ dashboard/         Next.js 16 web app (App Router) + API routes + Prisma
├─ extension/         Chrome Manifest V3 extension (Vite + @crxjs/vite-plugin)
├─ docs/              Project specification (Task.md)
├─ plans/             Per-AC implementation plans (Plan → Review → Implement)
├─ .claude/skills/    Task recipes for the AI assistant
├─ CLAUDE.md          AI agent rules (architecture invariants)
└─ docker-compose.yml Local PostgreSQL for development

The two apps are isolated — extension/ never imports from dashboard/ and vice versa. They communicate over HTTP only.

Tech stack

• Dashboard — Next.js 16 (App Router, Server Components), React 19, Tailwind CSS v4, TanStack Query v5, Framer Motion, D3.js
• Backend — Next.js Route Handlers, Prisma 7 (with @prisma/adapter-pg), Zod, google-auth-library, jsonwebtoken
• Extension — Manifest V3, Vite 7 + @crxjs/vite-plugin, TypeScript (strict)
• Database — PostgreSQL 16 (Docker for local, Neon for production)
• AI — LLM provider TBD (Week 3): OpenAI / Groq / Gemini / OpenRouter
• Deploy — Vercel (dashboard), .zip for local extension install

Versions in dashboard/package.json and extension/package.json are authoritative.

Prerequisites

• Node.js 20 or newer
• Docker Desktop (or Docker Engine + Compose plugin)
• Chrome 120+ (for loading the unpacked extension)

Setup

1. Clone and configure env

git clone https://github.com/BODMAT/worktrace.git
cd worktrace
cp dashboard/.env.example dashboard/.env
cp extension/.env.example extension/.env

The dashboard .env contains DATABASE_URL (already pointing at the docker-compose Postgres) plus GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, JWT_SECRET. The Google/JWT values are not required for Week 1 — leave them blank until the auth flow lands in Week 2.

2. Start PostgreSQL

docker-compose up -d

This boots a worktrace-postgres container on host port 5433 (mapped to container 5432, so it won't collide with a local Postgres on 5432). The DATABASE_URL in dashboard/.env.example already uses this port.

3. Run the dashboard

cd dashboard
npm install
npx prisma migrate dev
npm run dev

The dashboard is now at http://localhost:3000. The npm run dev step also implicitly runs prisma generate on first build, materializing the Prisma client and Zod schemas into dashboard/generated/ (both gitignored).

4. Build and load the extension

cd extension
npm install
npm run build

Then in Chrome:

1. Open chrome://extensions
2. Toggle Developer mode (top right)
3. Click Load unpacked
4. Select extension/dist/

The extension card should appear with no errors. For HMR-rebuild during active development use npm run dev instead of npm run build.

Verifying it works

1. Dashboard — http://localhost:3000 loads (Next.js placeholder page is fine for Week 1).

2. Extension — the card on chrome://extensions shows no errors; clicking the toolbar icon opens an empty popup; the service worker logs [worktrace] installed (visible via the extension's Inspect link).

3. API — a POST to the events endpoint round-trips through Postgres:

   curl -X POST http://localhost:3000/api/v1/events \
     -H "Content-Type: application/json" \
     -d '{"sessionId":"ctestsess0000000000000001","url":"https://example.com","title":"Hello","tags":["test"],"timestamp":"2026-05-15T12:00:00Z"}'

   A 201 response with the created event means the dashboard, Prisma, and Postgres are wired up correctly. (The sessionId must reference an existing Session row — create one via npx prisma studio or seed it manually.)

Project docs

• docs/Task.md — full acceptance criteria, weekly roadmap, git workflow
• CLAUDE.md — AI agent rules: architecture invariants, type-safety constraints, import boundaries
• .claude/skills/ — task recipes (api-route.md, prisma-model.md, extension-message.md)
• plans/ — per-AC implementation plans authored before each commit (the Plan → Review → Implement loop)

Deploy

• Dashboard — Vercel with Root Directory: dashboard. The build command prisma generate && next build (declared in dashboard/package.json) regenerates the Prisma client at build time since dashboard/generated/ is gitignored. Production database is Neon.
• Extension — distributed as a .zip of extension/dist/ for local install. Chrome Web Store packaging is scheduled for Week 4 AC 2.