Kemma Docs

Appearance

Kemma - Agent Instructions ​

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

Project Overview ​

Kemma 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 FastAPI backend, managed by Turborepo.

Technology Stack ​

  • Frontend (apps/web-client): React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui.
  • Backend (apps/server): Python 3.13, FastAPI, uv package manager.
  • Tools: ESLint, Prettier, Ruff (Python linting/formatting), Pyright (Python type checking), Playwright (E2E testing), Pytest.

Repository Structure ​

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

Development Workflow ​

Build & Run ​

  • Start All: npm run dev (Runs Frontend on 5173, Backend on 8000)
  • Frontend Only: turbo dev --filter=web-client
  • Backend Only: turbo dev --filter=server
  • 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 Python)
  3. Format: npm run format (Checks formatting)
  4. Tests:
    • All: npm run test
    • Frontend: turbo test --filter=web-client
    • Backend: turbo test --filter=server

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 (Python/FastAPI) ​

  • Type Hints: All function signatures must have type hints.
  • Style: Follow PEP 8 (enforced by Ruff).
  • Async: Use async def for route handlers.

Critical Files ​

  • apps/web-client/src/components/studio/Studio.tsx: The core mind map canvas implementation. Handle with care. Complex logic for drag/drop, panning, zooming, and node rendering resides here.
  • apps/web-client/src/lib/utils.ts: Common utility functions.
  • apps/server/kemma/main.py: FastAPI 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 uv add <package> in apps/server.
  7. Documentation: Update README.md if you add significant new features or change architecture.