mindmap.build docs

Appearance

mindmap.build - Agent Instructions ​

This document contains instructions for AI agents working on the mindmap.build codebase.

Project Overview ​

mindmap.build is a visual mind mapping platform (SaaS) combining infinite canvas collaboration with AI-powered ideation. It is a monorepo containing a React frontend and a Go Echo backend, managed by Turborepo.

Technology Stack ​

  • Frontend (apps/web-client): React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui.
  • Backend (apps/server-go): Go 1.25, Echo v4, SQLC, PostgreSQL.
  • Tools: ESLint, Prettier, Go Vet, Go Fmt, Playwright (E2E testing), Vitest.

Repository Structure ​

  • apps/web-client: Frontend application.
  • apps/server-go: Backend application.
  • package.json: Root scripts and workspace configuration.
  • turbo.json: Turborepo pipeline configuration.
  • README.md: Detailed project documentation.
  • WORKSPACE.md: Developer command reference.
  • DEPLOYMENT.md: Railway deployment architecture and configuration.

Development Workflow ​

Build & Run ​

  • Start All: npm run dev (Runs Frontend on 5173, Backend on 8001)
  • Frontend Only: turbo dev --filter=web-client
  • Backend Only: turbo dev --filter=server-go
  • Build Web: npm run build

Verification & Testing ​

Always run these checks before submitting changes:

  1. Check All: npm run check (Runs typecheck, lint, and tests for everything)
  2. Lint: npm run lint (Checks both JS/TS and Go)
  3. Format: npm run format (Checks formatting)
  4. Tests:
    • All: npm run test
    • Frontend: turbo test --filter=web-client
    • Backend: turbo test --filter=server-go

Coding Standards ​

Frontend (React/TypeScript) ​

  • Components: Use functional components with hooks.
  • Styling: Use Tailwind CSS utility classes. Avoid inline styles unless dynamic.
  • State Management: Use React local state for simple UI logic. The Mindmap Studio uses a complex state model described in README.md.
  • UI Components: Use shadcn/ui components located in apps/web-client/src/components/ui.
  • Imports & Encapsulation:
    • Barrel Files: The project uses index.ts files to define public APIs for modules (src/modules/*) and shared libraries (src/shared/*).
    • Rule: Always import from the barrel file (e.g., import { Button } from '@/shared/ui'), NOT the internal file path.
    • Exports: When creating new components or services, ensure they are exported from the corresponding index.ts if they need to be accessed externally.

Backend (Go) ​

  • Static Typing: Explicitly type all function parameters and return values.
  • Style: Follow standard Go formatting conventions (enforced by go fmt and go vet).
  • Error Handling: Explicitly check all errors (if err != nil) and wrap them with context (fmt.Errorf).
  • Framework: Use Echo v4 context (echo.Context) for all HTTP API route handlers.

Critical Files ​

  • apps/web-client/src/modules/studio/components/Studio.tsx: The core mind map canvas implementation. Handle with care. Complex logic for drag/drop, panning, zooming, reparenting, and node rendering resides here.
  • apps/web-client/src/shared/lib/utils.ts: Common utility functions.
  • apps/server-go/cmd/server/main.go: Backend entry point.

Agent Behavior Guidelines ​

  1. Explore First: Read README.md and WORKSPACE.md to understand the context.
  2. Verify Changes: distinct from "Testing", always verify that your changes (file creations, edits) were applied correctly using read_file or ls.
  3. Run Tests: Run relevant tests after making changes. Use npm run check to verify everything.
  4. Fix Lint/Type Errors: Ensure npm run check passes.
  5. Do Not Break Existing Features: Regression testing is key.
  6. Dependency Management:
    • Web: Use npm install in apps/web-client or root.
    • Server: Use go get <package> in apps/server-go.
  7. Documentation: Update README.md if you add significant new features or change architecture.