AlexandrAI AGENTS.md
agents-md

DeepDive Canvas API App Agent Guide

Project-specific AGENTS.md guidance for the DeepDive Canvas NestJS API app, feature modules, Prisma, Redis, realtime gateways, AI services, and test commands.

AGENTS.md

Guidance for coding agents working on DeepDive Canvas apps/api. The monorepo guide covers root commands; this file focuses on the NestJS backend boundary.

Project Overview

apps/api is the NestJS API server for DeepDive Canvas. It combines REST controllers, Socket.IO gateways, Prisma persistence, Redis infrastructure, scheduled tasks, auth guards, realtime collaboration, canvas nodes and edges, assets, meetings, agent shop, integrations, notifications, translations, and AI services.

Treat the API as the source of truth for backend behavior. Web UI changes that touch persistence, realtime events, AI workflows, workspace permissions, or external integrations usually need a corresponding API check.

Project Map

  • src/app.module.ts wires ConfigModule, ThrottlerModule, ScheduleModule, Prisma, Redis, and feature modules.
  • src/modules/auth owns login, registration, refresh, password changes, JWT strategy, guards, decorators, and auth service tests.
  • src/modules/workspaces owns workspace CRUD, membership, invite, lock canvas, list query DTOs, and member/admin guards.
  • src/modules/nodes and src/modules/edges own canvas graph persistence.
  • src/modules/ai, meetings, custom-agents, and agent-shop own AI collaboration and marketplace behavior.
  • src/modules/chat, realtime, and notifications own Socket.IO or realtime user communication surfaces.
  • src/modules/assets, drawings, slides, integrations, and translation own media, export, integration, and localization-adjacent features.
  • src/infrastructure/prisma and src/infrastructure/redis are the persistence and cache adapters.
  • src/common contains transform interceptors, health controller, encryption service, and shared utilities.

Setup Commands

~bash pnpm --filter @deepdive/api run start:dev pnpm --filter @deepdive/api run build pnpm --filter @deepdive/api run lint pnpm --filter @deepdive/api run test pnpm --filter @deepdive/api run test:e2e pnpm --filter @deepdive/api run db:generate pnpm --filter @deepdive/api run db:migrate pnpm --filter @deepdive/api run db:seed ~

Use local environment profiles for database, Redis, object storage, and provider settings. Do not publish concrete endpoints, ports, or credentials.

Change Rules For Agents

  • Keep DTO validation close to controllers and durable behavior in services.
  • Update Prisma schema, generated client, migration state, and service tests together when persistence changes.
  • Keep Socket.IO event names aligned with shared constants and web consumers.
  • Preserve workspace member/admin guard semantics around workspace, node, edge, asset, chat, and meeting actions.
  • Keep AI provider and integration credentials behind config/services; do not pass raw secrets through DTOs.
  • If a feature module emits user-visible state, check web components and shared types before renaming fields.
  • Avoid adding cross-module imports that bypass service boundaries.

Verification

Run the smallest focused check first:

~bash pnpm --filter @deepdive/api run test -- <module-or-spec> pnpm --filter @deepdive/api run lint pnpm --filter @deepdive/api run build ~

For database changes, also run the Prisma generate and migration command. For realtime or collaboration changes, verify the related web consumer path.

Security Notes

Do not log JWTs, refresh tokens, provider keys, workspace invite secrets, upload object keys, Redis connection details, or private integration payloads. Keep rate limiting, guards, validation pipes, transform interceptors, and encryption helpers in the path for protected routes.

PR Checklist

  • DTO, service, module, and test changes are aligned.
  • Prisma and generated client effects are explicit.
  • Web and shared consumers were checked for event or payload changes.
  • Auth, workspace, asset, integration, or AI changes include focused security tests.