Skip to content

agents.md

Latest commit

 

History

History
88 lines (68 loc) · 3.84 KB

agents.md

File metadata and controls

88 lines (68 loc) · 3.84 KB
Raw

You are helping build a full-stack web application using React + Express + SQLite.

Current state: Local development prototype. No cloud deployment, no authentication, no external integrations.

Development Workflow (MUST FOLLOW)

Project Structure

  • Monorepo at app/ with npm workspaces: backend/ and frontend/
  • Backend: Express.js + better-sqlite3, runs on port 3001
  • Frontend: React + Vite, runs on port 5173 (proxies API to 3001)
  • Database: SQLite file at backend/app.db

How to Run

Always use npm scripts from the app/ directory. Never run node commands directly.

cd app

# Seed/reset the database
npm run seed

# Start both backend + frontend (uses concurrently)
npm run dev

Background terminal one-liners (ensures Node.js is on PATH):

Windows (PowerShell):

cd "<WORKSPACE_ROOT>\app"; $env:Path = "$env:ProgramFiles\nodejs;$env:SystemRoot\System32;$env:SystemRoot;" + $env:Path; npm run dev

macOS / Linux (Bash):

cd "<WORKSPACE_ROOT>/app" && export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH" && npm run dev

There are also helper scripts: start-dev.ps1 (Windows) and start-dev.sh (macOS/Linux).

Rules for the AI Agent

  1. Use npm run dev to start servers — never node src/index.js or npx node.
  2. Use npm run seed to seed the database — never node backend/src/seed.js.
  3. Kill port 3001 before starting if it's already in use:
    • Windows: Get-NetTCPConnection -LocalPort 3001 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }
    • macOS/Linux: lsof -ti:3001 | xargs kill -9 2>/dev/null
  4. The PATH in background terminals may not include Node.js. Fix per OS:
    • Windows: $env:Path = "$env:ProgramFiles\nodejs;$env:SystemRoot\System32;" + $env:Path
    • macOS/Linux: export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"
  5. Do not use npx node — it downloads a different Node.js version that breaks native modules (better-sqlite3).
  6. After schema or seed changes, always re-seed before testing.
  7. Do NOT spawn duplicate servers. Vite (frontend) has Hot Module Replacement and the backend uses node --watch — code changes reflect automatically. Only restart after re-seeding the database.
  8. Kill ALL stale servers before starting new ones — check ports 3001 + 5173–5175:
    • Windows: 
      Get-NetTCPConnection -LocalPort 3001,5173,5174,5175 -State Listen -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }
    • macOS/Linux: 
      lsof -ti:3001,5173,5174,5175 | xargs kill -9 2>/dev/null

Coding Conventions

  • ES Modules throughout ("type": "module" in both package.json files); use import/export, not require
  • No TypeScript yet (plain .js backend, .jsx frontend)
  • React functional components with hooks; no class components
  • SQL queries written inline in route handlers (no query builder or ORM)
  • CSS custom properties for theming in styles/tokens.css; no CSS-in-JS or Tailwind
  • Component-scoped CSS files (e.g. HomePage.css alongside HomePage.jsx)

Backend Pattern

Each route file:

  1. Imports db from ../db.js (synchronous better-sqlite3)
  2. Uses db.prepare().all() / .get() / .run()
  3. Returns JSON via res.json()
  4. Is mounted in index.js under /api

Frontend Pattern

  • Routing: App.jsx defines all <Route> elements
  • API layer: frontend/src/api/index.js — thin fetchJSON wrapper; all functions return promises
  • Styling: design tokens in styles/tokens.css (CSS custom properties), component-scoped CSS
  • Pages: one file per page in pages/, with matching .css file