Skip to content

CLAUDE.md

Latest commit

 

History

History
88 lines (61 loc) · 2.56 KB

CLAUDE.md

File metadata and controls

88 lines (61 loc) · 2.56 KB

Poppy-Local

Project Overview

Poppy-Local is a local-first relationship manager. It stores contacts, interactions, and reminders in SQLite, serves a small Express API, and renders a no-build vanilla JS frontend from public/index.html.

Tech Stack

  • Node.js
  • Express
  • better-sqlite3
  • SQLite with WAL mode
  • Vanilla HTML/CSS/JS frontend
  • Node built-in test runner for integration and smoke tests

Key Files

  • src/server.js: Express app, API routes, assistant brief logic, import/export, startup flow
  • src/db.js: SQLite connection, data directory resolution, schema bootstrap
  • public/index.html: Entire frontend UI, styles, client-side state, modal flows
  • public/manifest.json: PWA manifest
  • public/sw.js: Basic service worker for app-shell caching
  • public/favicon.svg: Brand favicon and manifest icon source
  • tests/api.test.js: API integration coverage
  • tests/e2e.test.js: end-to-end smoke test that boots the server process
  • tests/helpers/server-test-utils.js: shared test server startup and HTTP helpers

How To Run

npm install
npm start

The app is available at http://localhost:3456 by default.

Environment

  • PORT: HTTP port for the Express server
  • NODE_ENV: runtime mode, typically development, test, or production
  • POPPY_DB_PATH: full path to the SQLite database file

If POPPY_DB_PATH is unset, the app stores data under ~/.poppy-local/poppy.db.

Development Workflow

npm run dev

npm run dev uses Node's watch mode and restarts the server on backend changes. The frontend is static, so reloading the browser is enough after editing files in public/.

Recommended flow:

  1. Run npm run dev
  2. Make changes
  3. Run npm test
  4. Commit with a conventional commit message

Testing

npm test

The tests start isolated server processes with temporary SQLite databases so they do not touch your real local data.

Commit Conventions

Use Conventional Commits:

  • feat: add dark mode toggle
  • fix: handle missing reminder contact
  • docs: document import workflow
  • test: add health smoke test

Preferred format:

type(scope optional): short imperative summary

Developer Notes

  • Keep API responses stable unless a change is intentional and coordinated with the frontend.
  • The frontend is intentionally build-free; prefer small, direct edits over introducing tooling.
  • public/index.html contains both UI and client logic, so verify modal flows and dashboard refreshes after changes.
  • Import/export is treated as a portability contract; avoid breaking snapshot structure.