Kemma - Visual Mind Mapping Platform

Kemma is an advanced, interactive mind mapping SaaS application designed for creative professionals and teams. It combines intuitive visual collaboration with AI-powered ideation to help users brainstorm, organize thoughts, and innovate faster.

🎯 Overview

Kemma offers a modern, web-based mind mapping experience with:

Infinite Canvas: Pan and zoom to explore limitless workspace
AI-Assisted Brainstorming: Generate related ideas with the "Spark" feature
Real-time Interaction: Drag, edit, and organize nodes seamlessly
Auto-save: Changes persist automatically as you work
Keyboard Shortcuts: Efficient node creation and navigation
Context Menus: Quick access to common operations

🛠️ Technology Stack

Core Framework

React 19.2 - Modern UI framework with hooks and functional components
TypeScript 5.9 - Type-safe development with full IDE support
Vite 7.2 - Lightning-fast build tool and dev server with HMR (Hot Module Replacement)

React Router DOM 7.9 - Client-side routing for SPA navigation

UI & Styling

Tailwind CSS 4.1 - Utility-first CSS framework for rapid styling
@tailwindcss/vite - Native Tailwind integration with Vite
shadcn/ui - High-quality, accessible React components built on Radix UI
- @radix-ui/react-avatar - User profile avatars
- @radix-ui/react-context-menu - Right-click context menus
- @radix-ui/react-dropdown-menu - Dropdown interactions
- @radix-ui/react-slot - Composition utilities
Lucide React - Beautiful, consistent icon library
class-variance-authority - Type-safe component variants
clsx & tailwind-merge - Conditional class composition

Design System

Inter Font - Modern, readable typography
Glassmorphism - Backdrop blur effects for premium aesthetics
Navy & Teal Palette - Brand colors (kemma-navy, kemma-teal)

Development Tools

ESLint 9 - Code quality and consistency
TypeScript ESLint 8 - TypeScript-specific linting rules

🧠 Key Techniques & Architecture

Mind Map Studio Implementation (`Studio.tsx`)

The heart of Kemma is the Mindmap Studio, a sophisticated canvas-based editor. Here's how it works:

1. Data Model - Tree Structure

Nodes: Each node represents an idea/topic with properties:
- id: Unique identifier (randomly generated)
- parentId: Reference to parent node (creates hierarchy)
- text: Display content
- x, y: Absolute position on canvas
- color: Visual identifier for branch grouping
Dynamic Array Growth: Nodes are stored in React state as a dynamic array that grows automatically - no size limits beyond available memory.

2. Coordinate System & Transforms

Canvas Panning: Instead of moving individual nodes, a single container uses CSS transform: translate() for performance
Zoom Implementation: transform: scale() centered on mouse cursor using mathematical compensation:
```
newOffset = (mousePos / newZoom) - (mousePos / oldZoom) + oldOffset
```
Dual-Mode Interaction:
- isDragging: Move individual nodes
- isPanning: Move entire viewport
- Flags prevent conflicting mouse event handlers

3. Node Positioning Algorithm

Hierarchical Layout:
- Children positioned 200px to the right of parent
- Vertical spacing of 80px between siblings
- Offset calculated as: (siblingCount * 80) - 40
Color Inheritance:
- Direct children of root get unique branch colors from a 7-color palette
- All descendants inherit parent color for visual grouping

4. Rendering Architecture

Layer System:
1. SVG layer (z-index behind): Connection lines using cubic Bézier curves
2. HTML layer (z-index front): Interactive node elements
Connection Lines: Drawn with SVG paths using control points:
```
cp1 = { x: start.x + (deltaX * 0.5), y: start.y }
cp2 = { x: end.x - (deltaX * 0.5), y: end.y }
```
Creates smooth "S" curves that exit/enter nodes horizontally

5. Undo/Redo System

History Stack Pattern:
- history: Array of past node states (2D array: any[][])
- future: States undone, used for redo
State Capture Points:
- Before drag operations (dragStartNodes.current)
- Before text editing (textFocusState.current)
- On structural changes (add/delete)

6. Event Handling & UX Patterns

Click-to-Edit Pattern:

typescript

// First click: Select
// Second click on same node: Enter edit mode
if (!hasDragged && clickTargetWasSelected) {
  setEditingNodeId(nodeId);
}

Keyboard Shortcuts:

Tab: Add child node (even while editing)
Enter: Add sibling node (blur text first)
Delete/Backspace: Remove node and descendants
Cmd/Ctrl + Z: Undo
Cmd/Ctrl + Shift + Z or Cmd/Ctrl + Y: Redo

Context Menu: Right-click reveals options for adding children or deleting nodes

7. Auto-Save Strategy

Debounced Save: Uses useEffect with [isDragging] dependency
Only saves when isDragging transitions from true to false
Prevents excessive API calls during rapid mouse movements
Text changes save on blur event

8. AI "Spark" Feature

Purpose: Generate AI-assisted ideas as child nodes
Layout Intelligence:
- Calculates existing children count
- Positions new AI nodes below existing children to avoid overlap
- Applies same coloring rules as manual nodes
Error Handling: try/catch/finally ensures loading state resets even on failure

9. Responsive Node Sizing

Auto-expand:
- Max width: 40 characters (40ch)
- Text wraps vertically beyond max width
- Uses CSS Grid "ghost element" technique for auto-sizing
Long Text Handling:
- Truncates to 200 chars when unselected
- Shows "(more)" indicator
- Full text visible when selected

10. Touch & Mouse Support

All interaction handlers check for both:

typescript

const clientX = e.clientX || e.touches?.[0]?.clientX;

Supports onMouseDown, onTouchStart, etc.

📁 Project Structure

kemma/                           # Monorepo root
├── apps/
│   ├── web-client/              # React + TypeScript + Vite
│   │   ├── public/
│   │   │   └── logo.png         # App logo & favicon
│   │   ├── src/
│   │   │   ├── components/
│   │   │   │   ├── landing/     # Landing page components
│   │   │   │   ├── studio/
│   │   │   │   │   └── Studio.tsx  # 🎯 Main mindmap canvas
│   │   │   │   └── ui/          # shadcn/ui components
│   │   │   ├── pages/
│   │   │   │   ├── LandingPage.tsx  # Marketing homepage
│   │   │   │   └── UserHome.tsx     # Dashboard with mindmap list
│   │   │   ├── lib/
│   │   │   │   └── utils.ts     # Utility functions
│   │   │   ├── App.tsx          # Route definitions
│   │   │   ├── main.tsx         # React entry point
│   │   │   └── index.css        # Global styles
│   │   ├── index.html           # HTML shell with SEO meta tags
│   │   ├── package.json
│   │   ├── vite.config.ts
│   │   └── tsconfig.json
│   │
│   └── server/                  # FastAPI + Python backend
│       ├── kemma/               # Python package
│       │   ├── api/             # API routes
│       │   ├── db/              # Database models & config
│       │   ├── services/        # Business logic
│       │   └── main.py          # FastAPI application
│       ├── tests/               # pytest test suite
│       ├── pyproject.toml       # Python dependencies & config
│       └── uv.lock              # Locked dependencies
│
├── package.json                 # Root workspace config
├── WORKSPACE.md                 # Workspace documentation
└── README.md                    # This file

🚀 Getting Started

Prerequisites

Node.js 20+ and npm (for web-client)
Python 3.13+ (for server)
uv - Fast Python package manager: pip install uv

Installation

bash

# Clone the repository
git clone <repository-url>
cd kemma

# Install dependencies (Frontend & Backend)
npm install

# Install Python backend dependencies
cd apps/server && uv sync

Development

Run Everything (Frontend + Backend):

bash

npm run dev

Starts both servers in parallel using Turbo.
Frontend: http://localhost:5173
Backend: http://localhost:8000
API docs at http://localhost:8000/docs

Run Individually:

bash

turbo dev --filter=web-client
turbo dev --filter=server

Build for Production

bash

# Build web-client
npm run build

# Preview production build
cd apps/web-client && npm run preview

Code Quality

Linting:

bash

npm run lint         # Lint all packages

Formatting:

bash

npm run format       # Format all code

Type Checking:

bash

npm run typecheck    # TypeScript + Pyright

Testing:

bash

npm run test         # Run all tests

Full Validation (CI):

bash

npm run check        # typecheck + lint + test

💡 See WORKSPACE.md for complete command reference.

🗺️ Application Routes

Route	Component	Description
`/`	`LandingPage`	Marketing page with features, CTA
`/home`	`UserHome`	User dashboard with mindmap gallery
`/mindmap`	`Studio`	Interactive mindmap editor

🎨 Design Philosophy

Visual Hierarchy

Root Node: Large, bold, centered - dark gray (#333)
Branch Nodes: Vibrant colors (blue, purple, pink, orange, etc.)
Descendant Nodes: Inherit parent color

State Feedback

Selected: Blue ring, scale up 5%, elevated shadow
Editing: Subtle blue border, no shadow (clean focus)
Unselected: Minimal border, no shadow (symmetrical appearance)
Hover: Slight shadow on unselected nodes

Glassmorphism & Modern UI

Header uses backdrop-blur-sm for frosted glass effect
Floating instruction panel with white/80 opacity
Rounded corners (rounded-2xl, rounded-full)
Smooth transitions (transition-all duration-200)

🔑 Key Features Explained

Infinite Canvas

The canvas uses a viewport transformation pattern:

Background grid provides spatial reference
Pan by dragging empty space
Zoom with mouse wheel (centered on cursor)
Zoom controls show current scale percentage

Recursive Node Deletion

Deleting a node removes its entire subtree:

typescript

// Recursively find all descendants
const getDescendants = (parentId, allNodes) => {
  const children = allNodes.filter(n => n.parentId === parentId);
  return children.flatMap(child =>
    [child.id, ...getDescendants(child.id, allNodes)]
  );
};

Drag Offset Calculation

Prevents nodes from "snapping" to cursor on drag:

typescript

dragOffset = {
  x: (mouseX / zoom) - node.x - viewOffset.x,
  y: (mouseY / zoom) - node.y - viewOffset.y
}

Maintains relative click position within node bounds.

🤖 Future Enhancements

Real Firebase Integration: Replace mock saveMap() with Firestore persistence
Gemini AI Integration: Connect "Spark" feature to Google's Gemini API
Collaborative Editing: WebSocket-based real-time multi-user support
Templates: Pre-built mindmap structures (project planning, brainstorming, etc.)
Export: Generate images (PNG/SVG) or structured data (JSON/XML)
Custom Themes: User-selectable color palettes and node styles

📝 License

This project is private and proprietary.

👥 Contributing

This is a private project. For questions or collaboration inquiries, please contact the repository owner.

Built with ❤️ using React, TypeScript, and Vite

Kemma - Visual Mind Mapping Platform ​

🎯 Overview ​

🛠️ Technology Stack ​

Core Framework ​

Routing & Navigation ​

UI & Styling ​

Design System ​

Development Tools ​

🧠 Key Techniques & Architecture ​

Mind Map Studio Implementation (Studio.tsx) ​

1. Data Model - Tree Structure ​

2. Coordinate System & Transforms ​

3. Node Positioning Algorithm ​

4. Rendering Architecture ​

5. Undo/Redo System ​

6. Event Handling & UX Patterns ​

7. Auto-Save Strategy ​

8. AI "Spark" Feature ​

9. Responsive Node Sizing ​

10. Touch & Mouse Support ​

📁 Project Structure ​

🚀 Getting Started ​

Prerequisites ​

Installation ​

Development ​

Build for Production ​

Code Quality ​

🗺️ Application Routes ​

🎨 Design Philosophy ​

Visual Hierarchy ​

State Feedback ​

Glassmorphism & Modern UI ​

🔑 Key Features Explained ​

Infinite Canvas ​

Recursive Node Deletion ​

Drag Offset Calculation ​

🤖 Future Enhancements ​

📝 License ​

👥 Contributing ​

Kemma - Visual Mind Mapping Platform

🎯 Overview

🛠️ Technology Stack

Core Framework

Routing & Navigation

UI & Styling

Design System

Development Tools

🧠 Key Techniques & Architecture

Mind Map Studio Implementation (`Studio.tsx`)

1. Data Model - Tree Structure

2. Coordinate System & Transforms

3. Node Positioning Algorithm

4. Rendering Architecture

5. Undo/Redo System

6. Event Handling & UX Patterns

7. Auto-Save Strategy

8. AI "Spark" Feature

9. Responsive Node Sizing

10. Touch & Mouse Support

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Development

Build for Production

Code Quality

🗺️ Application Routes

🎨 Design Philosophy

Visual Hierarchy

State Feedback

Glassmorphism & Modern UI

🔑 Key Features Explained

Infinite Canvas

Recursive Node Deletion

Drag Offset Calculation

🤖 Future Enhancements

📝 License

👥 Contributing