AGENTS.md

Quick Commands

pnpm dev:backend    # Backend on https://localhost:3443
pnpm dev:frontend  # Frontend on https://localhost:5174
pnpm build         # Build backend -> dist/ + frontend
pnpm test          # Vitest unit tests
npx playwright test  # E2E tests (requires running backend + frontend)

Prerequisites

Node.js 22+, pnpm 10+
MongoDB on localhost:27017
Redis on localhost:6379
SSL certificates in ssl/ directory

Path Aliases

@/* maps to src/* (defined in tsconfig.json)

Test quirks

Vitest runs unit tests in tests/**/*.test.ts excluding tests/e2e/
Playwright e2e tests target https://code-dev.g4dge7.com:5174 (requires running dev servers)

Build output

Backend compiles to dist/ (TypeScript)
Frontend builds to frontend/dist/

TypeScript strictness

strict, noUnusedLocals, noUnusedParameters, noUncheckedIndexedAccess all enabled

Architecture

Backend: Express 5 + Socket.io + Mongoose + Redis sessions
Frontend: React 19 + Vite 8 + Tailwind CSS 4
Entry points: src/web-app.ts (backend), frontend/src/main.tsx (frontend)

GadgetId

All entity IDs use GadgetId (a string alias) from @gadget/api. Never use ObjectId.

Interfaces

import { GadgetId } from "@gadget/api";

interface IMyEntity {
  _id: GadgetId;
  // ...
}

Mongoose Schemas

import { nanoid } from "nanoid";

const MySchema = new Schema<IMyEntity>({
  _id: { type: String, default: () => nanoid() },
  // ...
});

Critical: Never add `unique` or `required` to `_id`

unique: true → duplicate index error at startup (MongoDB auto-creates unique index on _id)
required: true → save fails because default is assigned AFTER validation

See docs/gadget-id.md for full documentation.

1.7 KiB Raw Blame History