NodeDesk (MVP v0.1)

NodeDesk is a single-user "solo tech operating system" for tracking clients, systems, notes, and lightweight work logs (for billing summaries — not invoicing).

Stack

• Next.js (App Router) + TypeScript
• TailwindCSS
• Postgres + Prisma
• Auth: email/password (cookie session)
• Email (optional magic link): Resend
• Email verification (optional feature flag)
• Payments: Stripe Checkout + Customer Portal + Webhooks

Local setup (Docker)

1) Requirements

• Docker
• Docker Compose

2) Configure env

Copy .env.example to .env and fill values. At minimum:

• APP_URL=http://localhost:3000
• AUTH_SECRET (min 32 chars)

3) Run

docker compose up -d

This starts:

• db: Postgres on port 5432
• minio: S3-compatible storage on port 9000 (console on 9001)
• app: Next.js on port 3000

4) Stripe webhooks (local)

Use the Stripe CLI:

stripe login
stripe listen --forward-to http://localhost:3000/api/stripe/webhook

Copy the printed signing secret into STRIPE_WEBHOOK_SECRET.

Scripts

• npm run dev – dev server
• npm run build – production build
• npm run start – production server
• npm run lint – lint
• npm run prisma:migrate – run migrations
• npm run seed – seed demo data (customizable via SEED_EMAIL, SEED_PASSWORD env vars)
• npm run reset – reset all user data (optionally scoped to one user via --email)
• npm run demo-seed – seed demo data using default demo credentials
• npm run demo-reset – reset demo user data to baseline
• npm run test:e2e – Playwright tests

Demo Mode

The demo workflow is designed for onboarding and sales scenarios. It creates a rich, realistic dataset covering multiple clients, locations, systems, contacts, notes, work logs, and tags — all linked to a single demo user.

Quick start

# Reset demo user (clears all data for demo@nodedesk.local)
npm run demo-reset

# Seed fresh demo data
npm run demo-seed

Full workflow (any user)

# Reset data for a specific user, then re-seed
npm run reset -- --email user@example.com
npm run seed

Demo credentials

Env var	Default	Description
SEED_EMAIL	demo@nodedesk.local	Demo user email
SEED_PASSWORD	password123!	Demo user password

What gets created

The seed script provisions a full demo environment:

Resource	Count	Details
Users	1	demo@nodedesk.local with active subscription
Tags	5	critical, monthly-maintenance, vip-client, compliance, hipaa
Clients	3	Acme Corp (active), Smith & Associates Law (active), Greenfield Medical (active)
Locations	4	Across all clients (Main Office + Warehouse for Acme, one each for others)
Systems	17	Servers, workstations, network switches, printers, kiosks — with real hostnames and IPs
Contacts	5	IT directors, office managers, practice owners with email/phone
Notes	7	Infrastructure docs, compliance notes, backup schedules
Work logs	12	Realistic billable and non-billable entries with durations

Each system has realistic attributes (hostnames, IPs, OS versions, models, serials). Critical infrastructure (servers) is tagged. Work logs include detailed descriptions of completed work.

Documentation

• Agent Quickstart - Quick setup guide for AI assistants
• Architecture - System design and patterns
• Search - Search strategy, query syntax, and ops procedures
• Deployment - Production deployment guides
• Runbook - Environment matrix, Stripe webhooks, and deploy smoke checklist
• Environment Variables - Complete env reference
• API Reference - Endpoints and Server Actions
• Security - Security policy and best practices
• Contributing - Development workflow