AlexandrAI AGENTS.md
agents-md

DeepDive Canvas Agent Guide

Project-specific AGENTS.md guidance for the DeepDive Canvas pnpm monorepo, NestJS API, Vite React canvas app, shared package, and AI collaboration workflow.

AGENTS.md

Guidance for coding agents working on DeepDive Canvas. Humans read the user and developer docs; this guide keeps the command, boundary, and verification detail an agent needs.

Project Overview

DeepDive Canvas is a pnpm workspace named deepdive-canvas. The root coordinates three main workspaces:

  • apps/api/: NestJS API, Prisma, Socket.IO, JWT/auth, scheduling, Swagger, Gemini integration, Redis, and PostgreSQL persistence.
  • apps/web/: Vite React 18 + TypeScript client using Zustand, XYFlow, Radix UI, Mermaid, i18n, and export-oriented UI packages.
  • packages/shared/: shared TypeScript types and utilities built with tsup.

The product is an AI workspace/canvas, so preserve traceability between API contracts, shared types, front-end graph state, and any AI-response workflow changes.

Setup Commands

bashcd <project-root>
pnpm install
pnpm dev
pnpm build
pnpm test
pnpm typecheck
pnpm lint

Run package-specific commands when the change is scoped:

bashpnpm --filter @deepdive/api run start:dev
pnpm --filter @deepdive/api run db:generate
pnpm --filter @deepdive/api run db:migrate
pnpm --filter @deepdive/web run dev
pnpm --filter @deepdive/web run typecheck
pnpm --filter @deepdive/shared run build

Use run_local.sh only when you need the repo's saved local process runner. Do not encode machine-specific process state in committed code or public docs.

Code Style

  • Keep API modules under apps/api/src and follow NestJS module/controller/service boundaries.
  • Keep canvas/UI work in apps/web/src; reusable visual primitives should not be hidden inside route-level components.
  • Put cross-app contracts in packages/shared/src before duplicating type shapes in API and web code.
  • Prefer explicit DTOs, validation, and shared response types over ad hoc JSON shapes.
  • Keep AI workflow changes auditable: name the prompt/service/module boundary that owns each step.

Testing

  • API changes need pnpm --filter @deepdive/api run test; use e2e only for route or module wiring that Jest unit tests cannot cover.
  • Web changes need pnpm --filter @deepdive/web run typecheck and pnpm --filter @deepdive/web run build; add focused tests where a pure function or store transition can be isolated.
  • Shared package changes need pnpm --filter @deepdive/shared run build and the consuming package build.
  • Database changes require Prisma generation plus a migration command in the API package. Never hand-edit generated Prisma output.

Security

  • Keep DATABASE_URL, REDIS_URL, JWT_SECRET, and AI provider keys in runtime environment files only.
  • Do not print secrets in seed, migration, auth, Socket.IO, export, or AI-service logs.
  • Treat generated PDF/PPT/archive exports as user-facing data surfaces; avoid leaking internal IDs or prompts unless the product intentionally exposes them.

Commit And PR Rules

  • Use focused commits such as feat:, fix:, docs:, refactor:, and test:.
  • Mention which workspace packages changed and which verification commands passed.
  • When touching both API and web, state whether packages/shared was updated or why no shared contract change was needed.