ClippingKK Web

ClippingKK is a full-stack Next.js application for importing, organizing, and sharing Kindle highlights. The Next.js process serves the web UI, GraphQL and REST APIs, PostgreSQL-backed data access, Redis caching, and the BullMQ worker.

Requirements

• Node.js 26
• pnpm 10.25 (the version pinned in package.json)
• Docker with Compose for local PostgreSQL and Redis
• An OpenAI API key and model for AI features (optional for builds)

Local development

Install dependencies and create a local configuration:

pnpm install
cp .env.example .env.local
pnpm infra:up
pnpm db:migrate
pnpm codegen
pnpm dev

Edit .env.local before starting the app. The checked-in defaults connect to the PostgreSQL and Redis containers from compose.yaml. pnpm dev serves the web app and processes background jobs in the same process.

Generated GraphQL output under src/gql/ is intentionally ignored; pnpm codegen regenerates it. AI prompts are maintained in src/server/ai/prompts.ts. Set server-only OPENAI_API_KEY and OPENAI_MODEL before using AI features. The model must be supported by the installed TanStack AI OpenAI adapter. All AI generation requires an authenticated, active Premium subscription. Builds and non-AI features work without OpenAI credentials.

AI smoke checks

pnpm test covers premium access, prompt behavior, SSE cancellation and errors, and actual OTLP export to a loopback collector with a mocked model response. For a live check, configure OpenAI, start the app, sign in with an active Premium account, and open a clipping explanation and the book recommendation modal. Verify incremental output and cancellation on close, then enhance a comment. Check ai.generate spans, app.ai.generations, app.ai.duration, token counts, and correlated completion logs in your telemetry backend. Free and anonymous requests must fail before any provider call. Never include keys or prompt content in screenshots or telemetry.

Common commands

Command	Purpose
pnpm dev	Start the development server at http://localhost:3101.
pnpm build	Regenerate GraphQL artifacts and create a production build.
pnpm test	Run the Vitest suite in happy-dom.
pnpm typecheck	Type-check the application without emitting files.
pnpm lint	Check src/ with oxlint.
pnpm format:check	Verify formatting with oxfmt.
pnpm infra:full	Build and run the complete local stack in Docker.
pnpm infra:down	Stop the local infrastructure containers.

Application routes live in src/app, reusable UI in src/components, and server integrations in src/server and src/services. GraphQL operations and generated types are under src/schema and src/gql; tests live in test/ and beside focused source modules.

Deployment

Production supports Docker-based self-hosting. Use a versioned container image with external PostgreSQL and Redis services; the repository's compose.yaml contains development credentials and is not a production deployment file.

See DEPLOY.md for configuration, migrations, rollout, health checks, upgrades, and source builds.