AlexandrAI AGENTS.md
agents-md

DeepDive Canvas Web App Agent Guide

Project-specific AGENTS.md guidance for the DeepDive Canvas Vite React frontend, workspace routes, node canvas, collaboration UI, agent shop, and verification commands.

AGENTS.md

Guidance for coding agents working on DeepDive Canvas apps/web. This package is the React workspace surface for canvas, meetings, collaboration, and agent workflows.

Project Overview

apps/web is a Vite React app using React Router, Radix UI, Tailwind, Zustand, Socket.IO client, React Flow, mermaid, markdown rendering, PDF export, i18next, Framer Motion, and shared workspace contracts. It has public login/register routes, protected dashboard, agent shop, activity, profile, workspace canvas, node chat, and workspace settings routes.

The app is a work surface, not a landing page. Changes should preserve dense canvas workflows, predictable protected routing, shared UI primitives, collaboration indicators, and backend contract alignment.

Project Map

  • src/App.tsx declares public and protected route structure.
  • src/components/layouts contains auth, app, and workspace settings shells.
  • src/pages contains dashboard, workspace, node chat, agent shop, activity, auth, profile, and workspace settings pages.
  • src/components/ui contains shared primitives such as button, card, input, label, toast, pagination, markdown, mermaid, and persona icon.
  • src/components/workspace contains input panel, header, agent selection, invite modal, and settings sidebar.
  • src/components/nodes contains canvas nodes, overlays, context menu, radial menu, version history, comments, persona, synthesis, anchors, and expert selection.
  • src/components/collaboration contains presence avatars and node presence/chat indicators.
  • src/components/chat, search, slides, upload, ai, menus, and license cover domain-specific surface areas.
  • src/styles/globals.css owns global styling and Tailwind expectations.

Setup Commands

~bash pnpm --filter @deepdive/web run dev pnpm --filter @deepdive/web run build pnpm --filter @deepdive/web run lint pnpm --filter @deepdive/web run typecheck pnpm --filter @deepdive/web run preview ~

Use environment variables locally for API and socket origins. Public documentation should never include concrete private origins.

Change Rules For Agents

  • Keep route protection behavior explicit in PublicRoute and ProtectedRoute patterns.
  • Reuse shared UI primitives and layout shells before adding new visual components.
  • Keep canvas node, edge, and presence behavior aligned with API modules and shared event constants.
  • Do not hardcode backend response shapes in components when a shared type or service helper exists.
  • Preserve dense workspace ergonomics: avoid oversized marketing-style sections inside operational screens.
  • For new user-facing text, check the i18n path before adding literal strings.
  • Keep file upload, PDF export, markdown, and mermaid rendering inside their established component boundaries.

Verification

~bash pnpm --filter @deepdive/web run lint pnpm --filter @deepdive/web run typecheck pnpm --filter @deepdive/web run build ~

For API payload, socket, or auth changes, run matching backend tests or inspect the API module that owns the contract.

Security Notes

Do not expose access tokens, refresh tokens, workspace invite secrets, integration credentials, direct object-storage links, or private API origins in browser logs, fixtures, or docs. Keep protected routes guarded and avoid rendering raw untrusted markdown or mermaid content without the existing sanitizer path.

PR Checklist

  • Routes, shells, and protected navigation remain coherent.
  • Canvas and collaboration changes were checked against API/shared events.
  • UI uses existing primitives and token conventions.
  • Typecheck, lint, and build pass for frontend changes.