Development Setup

Run the API, the web client, the desktop app and the extension together on one machine.

The repository is a monorepo of four packages with no root orchestrator. Run each one in its own terminal.

#Prerequisites

Requirement	Version
Node.js	20 or newer
PostgreSQL	14 or newer
Windows	10 or 11, 64 bit for the desktop app

#1. API

bash

cd server
npm install
npx prisma migrate deploy
npm run dev          # http://localhost:5000

server/.env

PORT=5000
DATABASE_URL="postgresql://user:password@localhost:5432/timelens"
CLIENT_URL="http://localhost:3000"
JWT_SECRET="dev-secret"
CLERK_SECRET_KEY="sk_..."

#2. Web client

bash

cd client
npm install
npm run dev          # http://localhost:3000

The client talks to the API through NEXT_PUBLIC_API_URL, which defaults to http://localhost:5000/api. The desktop dev server occupies ports 5173 and 5174, which is why both are allow-listed in the API CORS configuration.

#3. Desktop app

bash

cd desktop
npm install
npm run dev

#4. Browser extension

bash

cd extension
npm run build
# chrome://extensions -> Developer mode -> Load unpacked -> extension/dist

#Check it works

Call the health route first. If it returns ok, the API is up. If db-test fails, the database is the problem, not the application.

bash

curl http://localhost:5000/api/health
curl http://localhost:5000/api/db-test

#House rules

Business logic belongs in services, never in controllers or routes.
Controllers validate with the shared validation helpers and throw AppError.
Anything that reaches the database goes through a service.
The extension and the server keep identical copies of the category rules.
User facing documentation changes ship with the behaviour change, in the same commit.

PreviousData Model