diff --git a/CLAUDE.md b/CLAUDE.md index 3083701d..3cb84dfd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -GraphDone is a graph-native project management system that reimagines work coordination through dependencies and democratic prioritization rather than hierarchical assignments. The project is in active development (v0.2.1-alpha) with core architecture implemented and working foundation. +GraphDone is a graph-native project management system that reimagines work coordination through dependencies and democratic prioritization rather than hierarchical assignments. The project is in active development (v0.2.2-alpha) with a fully working foundation across web application, GraphQL API, and graph database. ## Core Philosophy @@ -13,265 +13,1228 @@ GraphDone is a graph-native project management system that reimagines work coord - Human and AI agents collaborate as peers through the same graph interface - Designed for neurodivergent individuals and those who think differently about work -## Planned Architecture +## Technology Stack -### Technology Stack -- **Frontend**: React 18 with TypeScript, React Native for mobile, D3.js for graph visualization -- **Backend**: Node.js with TypeScript, GraphQL with Apollo Server, Neo4j with @neo4j/graphql -- **State Management**: Zustand -- **Styling**: Tailwind CSS -- **Build Tool**: Vite -- **Real-time**: WebSocket subscriptions -- **Infrastructure**: Docker, Kubernetes, GitHub Actions for CI/CD -- **Testing**: Playwright for E2E testing, Vitest for unit tests +**Core Stack:** +- **Frontend**: React 18 + TypeScript + Vite + Tailwind CSS + D3.js +- **Backend**: Node.js + TypeScript + Apollo Server + GraphQL +- **Database**: Neo4j 5.15-community with @neo4j/graphql auto-generated resolvers +- **Build System**: Turbo monorepo with npm workspaces +- **Testing**: Playwright (E2E) + Vitest (unit tests) +- **Infrastructure**: Docker + Docker Compose -### Project Structure (Implemented) -``` -packages/ -├── core/ # Graph engine and algorithms (✅ Complete) -├── web/ # React web application (✅ Complete) -├── server/ # GraphQL API server (✅ Complete) -└── agent-sdk/ # SDK for AI agent integration (🔄 Planned) +**Key Libraries:** +- `@neo4j/graphql` - Auto-generates GraphQL schema and resolvers from Neo4j +- `@apollo/client` - GraphQL client with caching and real-time subscriptions +- `lucide-react` - Consistent icon system throughout UI +- `d3` - Graph visualization and force simulation -Additional: -├── docs/ # Comprehensive documentation -├── scripts/ # Development and deployment scripts -└── .github/ # CI/CD workflows -``` +## Essential Commands -## Development Commands +### Quick Start +```bash +# Single command to get everything running +./start -The project has a fully implemented monorepo structure with these commands: +# Alternative quick start without full setup checks +./start quick +# Manual setup (advanced) +./tools/setup.sh && ./tools/run.sh +``` + +### Development Workflow ```bash -# Quick setup (recommended) -./tools/setup.sh # Complete environment setup -./tools/run.sh # Start all development servers +# Start all development servers (web on :3127, API on :4127) +npm run dev -# Manual setup -npm install # Install dependencies -cp .env.example .env # Create environment file -docker-compose up -d postgres # Start PostgreSQL -npm run db:migrate # Run database migrations +# Run tests +npm run test # All tests including E2E +npm run test:unit # Unit tests only +npm run test:e2e # E2E tests only +npm run test:coverage # With coverage report -# Development -npm run dev # Start all development servers (Turbo) -npm run test # Run all tests -npm run lint # Lint all packages -npm run typecheck # Type check all packages -npm run build # Build all packages +# Code quality +npm run lint # ESLint all packages +npm run typecheck # TypeScript check all packages +npm run build # Build all packages for production +``` -# Database operations -npm run db:seed # Seed Neo4j database with test data +### Database Operations +```bash +# Seed Neo4j with sample data (32 work items + relationships) +npm run db:seed -# Docker development -docker-compose -f deployment/docker-compose.dev.yml up # With hot reload -docker-compose up # Production-like environment +# Access Neo4j Browser +# http://localhost:7474 (neo4j/graphdone_password) ``` -## Key Concepts +### Package-Specific Development +```bash +# Core graph engine +cd packages/core && npm run dev -### Graph Structure -- **Nodes**: Outcomes, tasks, milestones, contributors (human and AI) -- **Edges**: Dependencies, relationships, priorities -- **Spherical Coordinates**: 3D positioning based on priority (center = highest priority) +# GraphQL API server +cd packages/server && npm run dev -### Priority System -- Executive flags create gravity wells but don't control entire structure -- Individual contributors can establish small gravity wells on periphery -- Anonymous democratic rating system for idea validation -- Priority determines resource allocation and position in spherical model +# React web application +cd packages/web && npm run dev -### Agent Integration -Agents are first-class citizens that: -- Read/write graph state through standard GraphQL endpoints -- Receive real-time notifications for graph changes -- Request compute resources based on node priority -- Coordinate with humans through the same interface +# MCP server for Claude Code integration +cd packages/mcp-server && npm run dev +``` + +## Architecture Overview -## Implementation Guidelines +### Monorepo Structure +``` +packages/ +├── core/ # Graph algorithms and data structures +├── server/ # GraphQL API with Neo4j integration +├── web/ # React frontend with D3.js visualization +└── mcp-server/ # Claude Code integration server +``` -When implementing features: +### Core Graph Engine (`packages/core/`) -1. **Graph-First Design**: All features should work within the graph paradigm -2. **Mobile-First UI**: Touch interactions must be primary, not an afterthought -3. **Agent Parity**: Any action a human can take, an agent should be able to take via API -4. **Democratic by Default**: Community validation mechanisms should be built into core features -5. **Accessibility**: Design for neurodiversity and different cognitive styles +The heart of GraphDone is a custom graph implementation: -## Development Commands +**Key Classes:** +- `Graph` - Main container with adjacency lists, pathfinding, cycle detection +- `Node` - Individual graph nodes with spherical positioning based on priority +- `Edge` - Typed connections (DEPENDS_ON, BLOCKS, ENABLES, etc.) +- `Priority` - Multi-dimensional priority system (executive, individual, community) -```bash -# Initial setup -./tools/setup.sh # Set up development environment -./tools/run.sh # Start development servers -./tools/test.sh # Run test suite with linting and type checking -./tools/build.sh # Build all packages -./tools/deploy.sh # Deploy to staging/production -./tools/document.sh # Generate and deploy documentation - -# Docker development -./tools/run.sh --docker-dev # Start with Docker (development) -./tools/run.sh --docker # Start with Docker (production) - -# Package-specific testing -./tools/test.sh --package core # Test specific package -./tools/test.sh --coverage # Run with coverage report -./tools/test.sh --watch # Run in watch mode - -# Turbo commands (alternative) -npm run dev # Start all development servers -npm run build # Build all packages -npm run test # Run all tests -npm run lint # Lint all packages -npm run typecheck # Type check all packages -``` - -## Current Implementation Status - -✅ **Completed:** -- Monorepo structure with Turbo for build orchestration -- Core graph engine with Node, Edge, Priority calculation, and full graph operations -- Neo4j integration with @neo4j/graphql auto-generated resolvers -- GraphQL API server with comprehensive schema and WebSocket subscriptions -- React web application with D3.js graph visualization and user-friendly error handling -- TypeScript configuration across all packages -- Playwright and Vitest testing infrastructure with E2E tests -- Docker development and production configurations with Neo4j 5.15-community -- Enhanced development scripts with automatic dependency management -- GitHub Actions CI/CD workflows for testing, building, and deployment -- Comprehensive documentation structure and branding (favicon, logos) - -🏗️ **Architecture Implemented:** -- `packages/core/` - Graph engine with priority calculation, node/edge management, path finding, cycle detection -- `packages/server/` - GraphQL API with Neo4j schema, Apollo Server with @neo4j/graphql, WebSocket subscriptions -- `packages/web/` - React app with Vite, Tailwind CSS, D3.js visualization, Apollo Client, enhanced error handling -- Docker configurations for development and production with Neo4j 5.15-community -- Kubernetes-ready manifests (planned in deployment docs) -- Full CI/CD pipeline with testing, security scanning, and deployment -- Production deployment verified and tested - -🎯 **Ready for Development:** -All foundation pieces are in place. To continue development: -1. Run `./start` to initialize the development environment automatically -2. Access the working application at http://localhost:3127 -3. Use GraphQL Playground at http://localhost:4127/graphql -4. Backend status at http://localhost:3127/backend shows Neo4j architecture -5. Begin implementing specific features using the established patterns -6. Add more comprehensive tests using the Playwright and Vitest setup -7. Enhance the Neo4j schema and GraphQL resolvers as needed - -## Core Architecture - -### Graph Engine (`packages/core/`) -The heart of GraphDone is a custom graph engine with these key classes: - -- **Graph**: Main graph container with nodes/edges, adjacency lists, pathfinding, cycle detection -- **Node**: Individual graph nodes with priority calculation, spherical positioning -- **Edge**: Connections between nodes with types (DEPENDENCY, BLOCKS, etc.) -- **Priority**: Multi-dimensional priority system (executive, individual, community) -- **PriorityCalculator**: Algorithms for computing weighted priorities and spherical positions - -Key files: -- `packages/core/src/graph.ts` - Main Graph class with all operations -- `packages/core/src/node.ts` - Node implementation with priority management -- `packages/core/src/priority.ts` - Priority calculation logic -- `packages/core/src/types.ts` - TypeScript definitions +**Core Types:** +- `NodeType` - OUTCOME, TASK, MILESTONE, IDEA +- `NodeStatus` - PROPOSED, ACTIVE, IN_PROGRESS, BLOCKED, COMPLETED, ARCHIVED +- `EdgeType` - 11 relationship types for complex dependency modeling +- `SphericalCoordinate` - 3D positioning where radius = inverse priority ### GraphQL API (`packages/server/`) -Apollo Server with real-time subscriptions: -- **Database**: Neo4j 5.15-community with APOC plugins -- **Schema**: Auto-generated GraphQL schema with @neo4j/graphql -- **Resolvers**: Automatically generated from Neo4j schema -- **Subscriptions**: Real-time WebSocket updates -- **Health Check**: `/health` endpoint for monitoring +**Architecture:** +- Auto-generated schema using `@neo4j/graphql` from database constraints +- Real-time subscriptions for live updates +- Direct Neo4j authentication (no Prisma/PostgreSQL dependencies) +- Authentication with Passport.js (Google OAuth, GitHub OAuth, LinkedIn OAuth + local) +- Health check endpoint at `/health` -Key files: -- `packages/server/src/index.ts` - Apollo Server setup with WebSocket support -- `packages/server/src/schema/neo4j-schema.ts` - Neo4j GraphQL schema definitions -- `packages/server/src/scripts/seed.ts` - Database seeding script -- `packages/server/src/context.ts` - GraphQL context with Neo4j driver +**Key Files:** +- `src/schema/neo4j-schema.ts` - Core GraphQL type definitions +- `src/schema/auth-schema.ts` - Authentication GraphQL schema extensions +- `src/resolvers/auth.ts` - Authentication resolvers and OAuth handlers +- `src/index.ts` - Apollo Server setup with WebSocket support +- `src/scripts/seed.ts` - Database seeding with realistic test data ### Web Application (`packages/web/`) -React app with D3.js visualization: -- **Framework**: React 18 + TypeScript + Vite -- **Styling**: Tailwind CSS -- **Visualization**: D3.js for interactive graph rendering -- **State**: Apollo Client for GraphQL state management -- **Routing**: React Router for navigation +**Component Architecture:** +- `InteractiveGraphVisualization` - Enhanced D3.js force-directed graph with advanced interactions +- `SafeGraphVisualization` - Error-boundary wrapped graph visualization +- `ViewManager` - Orchestrates dashboard, table, kanban, gantt, calendar, and card views +- `Workspace` - Main layout with graph selector, view modes, and data issues tracking +- `useDialogManager` - Centralized hook for managing all dialogs/overlays lifecycle +- Multiple modal components for CRUD operations (Create, Edit, Delete, Connect, etc.) + +**Key Features:** +- Graph selector with hierarchical tree navigation (Team/Personal/Templates) +- Real-time updates via Apollo Client subscriptions +- Multiple visualization modes (graph, dashboard, table, kanban, gantt, calendar, card) +- Responsive design with tropical lagoon animated background +- Dialog manager for efficient click-outside-to-close behavior +- Right sidebar with contextual information and actions +- Activity feed for real-time collaboration awareness + +**Constants and Styling:** +- `workItemConstants.tsx` - Centralized icon mappings, color schemes, and gradients +- Priority-based coloring system with animated elements +- Consistent Tailwind classes with transparency and backdrop blur +- Modern card-based layouts with dynamic theming + +### Database Schema (Neo4j) + +**Core Node Types:** +- `WorkItem` - Primary nodes with title, description, type, status, priority +- `Graph` - Container nodes for organizing work items +- `Team` - Organizational structure +- `User` - Authentication and ownership + +**Relationships:** +- `DEPENDS_ON` - Core dependency relationships +- `ASSIGNED_TO` - Work assignment +- `BELONGS_TO` - Graph membership +- Plus 8 other relationship types for complex modeling + +## Key Implementation Patterns + +### Graph-First Design +All features work within the graph paradigm. Every action creates or modifies nodes and edges rather than traditional hierarchical structures. + +### Democratic Prioritization +Priority is multi-dimensional: +- Individual priority (personal importance) +- Community priority (democratic validation) +- Executive priority (strategic flags) +- Computed priority (algorithmic combination) + +### Agent Integration +AI agents are first-class citizens accessing the same GraphQL endpoints as humans. The MCP server provides natural language interface for Claude Code. -Key files: -- `packages/web/src/App.tsx` - Main application router -- `packages/web/src/components/GraphVisualization.tsx` - D3.js graph component -- `packages/web/src/lib/apollo.ts` - GraphQL client configuration +### Real-Time Collaboration +WebSocket subscriptions ensure all users see live updates to the graph structure and work item status. + +### Mobile-First UI +Touch interactions are primary, with hover states as enhancements. All components work on mobile screens. + +### Dialog Management System +**CRITICAL DESIGN PATTERN**: All dialogs, overlays, dropdowns, and temporary UI elements use a centralized dialog manager for consistent behavior. + +**Dialog Manager Philosophy:** +- Dialogs should close when users click outside them (on empty graph space) +- Users shouldn't have to hunt for X buttons - click-outside-to-close is more efficient +- Centralized management ensures proper cleanup and prevents memory leaks +- All temporary UI elements register/unregister with the global manager + +**Implementation via `useDialogManager` Hook:** +```jsx +import { useDialog, useDialogManager } from '@/hooks/useDialogManager'; + +// Component using a dialog +const MyComponent = () => { + const [isOpen, setIsOpen] = useState(false); + + // Register this dialog with the manager + useDialog(isOpen, () => setIsOpen(false)); + + return ( + <> + {isOpen && ( +
+ {/* Dialog content */} +
+ )} + + ); +}; + +// Component that needs to close all dialogs +const GraphView = () => { + const { closeAllDialogs } = useDialogManager(); + + const handleBackgroundClick = () => { + closeAllDialogs(); // Closes all registered dialogs + }; +}; +``` + +**Current Dialog Implementations:** +- Graph selector dropdown in `Workspace.tsx` +- Data Issues panel in `Workspace.tsx` +- All modal dialogs (Create, Edit, Delete, Connect, etc.) +- Right sidebar panels and overlays +- Filter/search dropdowns in views + +**Dialog Requirements:** +- Register all temporary UI with `useDialog` hook +- Implement click-outside-to-close behavior +- Clean up properly on unmount +- Use React portals for z-index issues when needed ## Testing Strategy -All packages use Vitest for testing: +**Unit Tests (Vitest):** +- Graph algorithms and priority calculations +- Component logic and utility functions +- GraphQL resolver behavior + +**E2E Tests (Playwright):** +- Full user workflows across graph visualization +- Error handling and recovery scenarios +- Multi-browser compatibility +- Screenshot comparisons for visual regression +**Test Commands:** ```bash -# Run all tests -npm run test +# Run specific test suites +npm run test:e2e:core # Core functionality +npm run test:e2e:error-handling # Error scenarios +playwright test --ui # Interactive test runner +``` + +## Current Development Focus + +### UI/UX Design Language Standardization +The project is actively establishing a cohesive design language across all views: + +**Layout Standards:** +- **Left Sidebar**: Consistent navigation with collapsible sections +- **Top Bar**: Graph selector (left) + view mode buttons (center) + actions (right) +- **Transparent Backgrounds**: Semi-transparent panels with backdrop blur for "zen mode" +- **Tropical Lagoon Animation**: Consistent animated background across all views + +**Visual Consistency:** +- Standardized spacing, typography, and color schemes +- Consistent hover states and interaction patterns +- Unified modal and dropdown styling +- Priority-based coloring system with animated elements + +### Graph vs View Conceptual Clarification + +**Graphs are Dynamic Filters, Not Static Views:** +A "graph" in GraphDone represents a specific filtered view of your data, not just the visualization mode. Examples: + +- **Project Graph**: Filters to show only nodes related to "Mobile App Redesign" +- **Team Graph**: Shows all work items assigned to or owned by the Design Team +- **Epic Graph**: Filters to show tasks, outcomes, and milestones under a specific epic +- **Custom User Graph**: Personal filtered view like "My High Priority Tasks" +- **Custom Team Graph**: Shared filtered view like "This Sprint's Deliverables" + +**Graph Organization:** +- Organized in hierarchical folders (Team/Personal/Templates) +- Navigable via the prominent dropdown selector in the top bar +- Each graph can be viewed in multiple visualization modes (graph, table, kanban, etc.) +- The same underlying filtered dataset appears consistently across all view modes + +### Inline Editing Priority + +**Current UX Problem**: Users must open full edit dialogs to modify node properties +**Target UX**: Click-to-edit any property directly from any view + +**Implementation Needs:** +- **Table View**: Click on type, status, contributor, priority, due date cells to edit inline +- **Graph View**: Click on node badges/indicators to edit properties without opening modal +- **Kanban View**: Drag-and-drop status changes, click-to-edit other properties on cards +- **Dashboard View**: Click on metrics/stats to filter or edit related items + +**Technical Requirements:** +- Consistent inline editing components across all views +- Real-time updates via GraphQL subscriptions +- Optimistic UI updates with rollback on failure +- Keyboard navigation support for accessibility + +## Development Philosophy + +From the codebase philosophy: "You are building tools that help everyone. Take it seriously, take pride in your work, don't fake tests, we are building open source software which will help people connect with each other and work together." -# Run specific package tests -npm run test --filter=@graphdone/core -npm run test --filter=@graphdone/server -npm run test --filter=@graphdone/web +The future is decentralized, free, and compassionate. This guides all architectural decisions toward democratic coordination rather than hierarchical control. -# Run with coverage -npm run test -- --coverage +## Current UI Evolution: Slick Dialog Revolution + +GraphDone is undergoing a **major UI transformation** moving away from heavy modal dialogs toward slick, contextual, inline-style editors. This shift prioritizes **immediate feedback, minimal context switching, and delightful micro-interactions**. + +### The New Dialog Paradigm: Select Relationship Type + +**🎯 Target Design Pattern**: The **Select Relationship Type dialog** (`InteractiveGraphVisualization.tsx:3520-3681`) represents the new gold standard for GraphDone dialogs: + +**Key Characteristics:** +- **Contextual positioning**: Appears directly next to the element being edited +- **Immediate visual feedback**: Real-time updates with smooth animations +- **Minimal chrome**: No heavy borders, headers, or separate modals +- **Rich micro-interactions**: Hover effects, scaling, gradient overlays +- **Elegant selection states**: Current selection clearly indicated with animated pulse +- **Sophisticated styling**: Gradient backgrounds, backdrop blur, modern rounded corners +- **Professional animations**: Staggered reveal (30ms delays), scale transforms, smooth transitions + +```jsx +// NEW PATTERN: Slick contextual editor +{editingEdge && createPortal( +
+
+
+ {RELATIONSHIP_OPTIONS.map((option, index) => ( + + ))} +
+
+
, + document.body +)} ``` -Current test files: -- `packages/core/tests/` - Graph engine unit tests -- `packages/server/tests/` - API integration tests -- `packages/web/src/test/` - React component tests +### The Old Pattern Being Replaced: Heavy Modal Dialogs -## Database Schema +**❌ Legacy Pattern**: Traditional modals like `EditNodeModal.tsx` with: +- Full-screen overlays requiring dedicated focus +- Heavy form structures with multiple sections +- Save/Cancel button patterns +- Context switching away from the graph +- Verbose layouts with lots of whitespace -Neo4j with these main node types and relationships: -- **WorkItem**: Graph nodes with spherical coordinates and priorities -- **Edge**: Connections between nodes with types (DEPENDS_ON, BLOCKS, etc.) -- **Contributor**: Users and AI agents in the system -- **WORKS_ON**: Relationships between contributors and work items +### Planned Dialog Transformations -Key database operations: -```bash -npm run db:seed # Add test data with 32 work items and relationships -# Access Neo4j Browser at http://localhost:7474 (neo4j/graphdone_password) +**🚀 Migration Strategy**: Replace heavy dialogs with contextual, inline-style editors: + +1. **Node Editing** → Context menu with expandable sections +2. **Status Changes** → Dropdown selector with immediate effect +3. **Type Selection** → Icon grid with hover previews +4. **Priority Adjustment** → Inline slider with real-time visual feedback +5. **Connection Management** → Drag-and-drop with contextual relationship picker + +## Visual Language Consistency: The Calm Environment System + +GraphDone implements a **cohesive visual language** designed to create a calm, unified environment rather than aggressive full-screen takeovers. All pages follow consistent patterns to maintain visual harmony with the tropical lagoon background. + +### The Three-Section Top Bar Pattern + +**🎯 Standard Layout** (`Workspace.tsx:202-644`): Every page should implement this top bar structure: + +```jsx +
+
+
+ {/* LEFT SECTION: Primary Action/Selector */} +
+ {/* Graph selector, search, primary navigation */} +
+ + {/* CENTER SECTION: Mode/View Buttons */} +
+
+ {/* Clear icon buttons for different views/modes */} +
+
+ + {/* RIGHT SECTION: Status/Actions */} +
+ {/* Connection status, data health, secondary actions */} +
+
+
+
``` -## Package-Specific Commands +**Visual Characteristics:** +- **Semi-transparent background**: `bg-gray-800/30 backdrop-blur-sm` allows lagoon animation to show through +- **Clear sectioning**: Left (primary), Center (modes), Right (status/actions) +- **Consistent height**: `h-16` for all top bars +- **Subtle borders**: `border-b border-gray-700/20` for gentle separation -### Core Package (`packages/core/`) -```bash -cd packages/core -npm run build # Build TypeScript -npm run dev # Watch mode -npm run test # Run Vitest tests -npm run lint # ESLint -npm run typecheck # TypeScript check +### The Transparent Sidebar Pattern + +**🌊 Zen Mode Sidebar** (`Layout.tsx:74-155`): Left sidebar with generous transparency: + +```jsx +
+
+ {/* Logo section with consistent branding */} +
+ GraphDone Logo + GraphDone +
+ + {/* Navigation with modern tab styling */} + +
+
``` -### Server Package (`packages/server/`) +**Design Principles:** +- **High transparency**: `bg-gray-800/95` allows subtle animation visibility +- **Backdrop blur**: Creates depth while maintaining readability +- **Active state styling**: Green accent with left border for current page +- **Consistent spacing**: `space-y-2` for navigation items, `px-4 py-6` for container + +### Universal Background Animation + +**🏝️ Tropical Lagoon System** (`Layout.tsx:31-53` & `index.css:6-175`): + +Every page includes the same calming background animation: +```jsx +
+
+
+
+ {/* ... 10 caustic layers + 10 shimmer layers */} +
+ {/* Page content with transparency to show animation */} +
+``` + +**Animation Characteristics:** +- **10 caustic layers**: Overlapping organic motion patterns +- **10 shimmer layers**: Subtle light scattering effects +- **Parameterized timing**: 40+ CSS custom properties for easy theming +- **Performance optimized**: Uses `transform` and `opacity` only + +### Visual Consistency Requirements + +**🎨 All Pages Must Follow**: This visual language creates a cohesive environment where users feel they're in one calm application rather than jumping between different interfaces. + +**Implementation Checklist for New Pages:** +- ✅ **Transparent top bar**: `bg-gray-800/30 backdrop-blur-sm` +- ✅ **Three-section layout**: Left (primary), Center (modes), Right (status) +- ✅ **Consistent height**: `h-16` top bar +- ✅ **Universal background**: Include lagoon caustic animation layers +- ✅ **Transparent sidebar**: `bg-gray-800/95 backdrop-blur-sm` if applicable +- ✅ **Green accent system**: Active states use `green-600/20` backgrounds +- ✅ **Backdrop blur everywhere**: Maintain depth while showing animation +- ✅ **Subtle borders**: Use `border-gray-700/20` for gentle separation + +**Current Implementation Status:** +- ✅ **Workspace**: Full three-section pattern with center view modes +- ✅ **Layout**: Universal sidebar with transparent design +- ❌ **Ontology**: Needs top bar transparency and center mode buttons +- ❌ **AI & Agents**: Needs visual language consistency +- ❌ **Analytics**: Needs top bar three-section pattern +- ❌ **Settings**: Needs transparent styling integration +- ❌ **Admin**: Needs visual consistency with workspace pattern +- ❌ **Backend Status**: Needs top bar with right-aligned status indicators + +**Anti-Patterns to Avoid:** +- ❌ **Solid backgrounds**: Blocks the calming lagoon animation +- ❌ **Heavy modal takeovers**: Breaks the zen-like environment +- ❌ **Inconsistent heights**: Creates jarring visual jumps +- ❌ **Missing backdrop blur**: Reduces depth and visual hierarchy +- ❌ **Different accent colors**: Breaks the green-focused brand consistency + +## Theme Pack Plugin Architecture + +GraphDone implements a **sophisticated theme system** designed for extensibility via plugin architecture: + +### Current Theme Structure + +**🎨 Centralized Theme System** (`workItemConstants.tsx:934-1049`): +- **Multi-context gradients**: Different styles for table, card, kanban, dashboard views +- **Static Tailwind classes**: Ensures proper compilation and performance +- **Centralized color mapping**: Hex colors mapped to Tailwind utility classes +- **View-specific styling**: Each view type gets optimized gradient patterns + +```typescript +export type GradientStyle = 'table' | 'card' | 'kanban' | 'dashboard'; + +export const getTypeGradientBackground = (type: WorkItemType, style: GradientStyle): string => { + const gradientMap: Record = { + 'green-500': 'bg-gradient-to-r from-green-500/15 via-green-500/5 to-green-500/15', + 'blue-500': 'bg-gradient-to-r from-blue-500/15 via-blue-500/5 to-blue-500/15', + // ... full color palette + }; + return gradientMap[tailwindColor] || fallback; +}; +``` + +### Tropical Lagoon Animation System + +**🌊 CSS Custom Properties** (`index.css:6-43`): +- **Parameterized animations**: Easy to modify via CSS variables +- **Layer-based caustics**: Multiple overlapping animation layers +- **Configurable timing**: Independent duration, amplitude, opacity controls +- **Theme-agnostic structure**: Animation parameters separate from color schemes + +```css +:root { + --lagoon-1-duration: 45s; + --lagoon-1-x-amplitude: 20%; + --lagoon-shimmer-opacity-max: 0.24; + /* ... 40+ customizable parameters */ +} +``` + +### Plugin Architecture Readiness + +**🔌 Theme Pack Extensions** (planned): +```typescript +interface ThemePackManifest { + name: string; + version: string; + gradients: GradientStyleMap; + animations: AnimationConfigMap; + customProperties: CSSCustomPropertyMap; + components?: ComponentOverrideMap; +} + +// Load theme pack dynamically +const loadThemePack = async (themePack: ThemePackManifest) => { + // Inject CSS custom properties + // Override gradient mappings + // Apply component style overrides +}; +``` + +## Next Priority Tasks + +### 1. Graph View Architecture Refactoring (URGENT - 4,015 lines) +- [ ] **Phase 1: Extract Core GraphEngine** - Pure D3 visualization without UI state +- [ ] **Phase 2: Extract MiniMapPlugin** - Swappable themes/backgrounds as plugin +- [ ] **Phase 3: Extract NodeEditorPlugin** - Contextual editing as composition +- [ ] **Phase 4: Extract RelationshipSelectorPlugin** - Slick selector as plugin +- [ ] **Phase 5: Create Plugin System** - Renderer with priority/z-index management +- [ ] **Phase 6: Theme Integration** - Plugin-aware theme switching + +### 2. Complete Node Editing Simplification (Critical Path) +- [ ] **Replace EditNodeModal with contextual editor** using Select Relationship Type pattern +- [ ] Implement inline property editing (status, type, priority) in graph view +- [ ] Add drag-to-reposition for contextual dialogs +- [ ] Test click-outside-to-close behavior with dialog manager integration + +### 3. Slick Dialog Migration Strategy +- [ ] **Create reusable SlickSelector component** based on Select Relationship Type pattern +- [ ] **Port node context menu** from EditNodeModal to contextual overlay +- [ ] **Implement inline status changer** with immediate visual feedback +- [ ] **Add priority slider widget** with real-time node repositioning +- [ ] **Create type selector grid** with icon hover previews and instant updates + +### 4. Clean Architecture Guidelines + +**🏗️ Anti-Pattern: Monolithic Components** +- ❌ Components over 500 lines require architectural review +- ❌ More than 10 useState hooks in a single component +- ❌ Mixing UI state with business logic in one place +- ❌ Global window functions for component communication + +**✅ Recommended Patterns**: +- **Composition over Configuration**: Build complex UIs from small, focused components +- **Plugin Architecture**: Major features as swappable plugins with clean interfaces +- **Theme Awareness**: All UI elements consume theme context for swappable styling +- **Event-Driven Communication**: Use context and callbacks, not global state +- **Single Responsibility**: Each component has one clear purpose + +## File Structure & Documentation Standards + +### 🗂️ Complete Modular Architecture File Structure + +**Root Level Organization:** +``` +packages/web/src/ +├── components/ +│ ├── graph/ # Complex feature modules +│ ├── ui/ # Simple reusable components +│ └── slick/ # Slick dialog components +├── pages/ # Route-level page components +├── hooks/ # Shared business logic hooks +├── contexts/ # React context providers +├── themes/ # Theme configurations +├── types/ # TypeScript type definitions +└── utils/ # Pure utility functions +``` + +### 🎯 Graph Feature Module Structure (Reference Pattern) + +``` +packages/web/src/components/graph/ +├── index.ts # Public API exports +├── README.md # Feature documentation +├── GraphView.tsx # Composition root (< 100 lines) +├── GraphEngine.tsx # Core D3 logic (< 300 lines) +├── GraphProvider.tsx # Context & state management +├── GraphContext.ts # TypeScript context definitions +├── hooks/ +│ ├── index.ts # Hook exports +│ ├── useGraphState.ts # State management (< 150 lines) +│ ├── useGraphTheme.ts # Theme switching logic +│ ├── useGraphEvents.ts # Event handling logic +│ └── useGraphAnimation.ts # Animation utilities +├── plugins/ +│ ├── index.ts # Plugin registry & exports +│ ├── PluginRenderer.tsx # Plugin orchestration +│ ├── BasePlugin.types.ts # Plugin interface definitions +│ ├── MiniMapPlugin/ +│ │ ├── index.ts # Plugin export +│ │ ├── MiniMapPlugin.tsx # Main plugin component (< 200 lines) +│ │ ├── MiniMapCanvas.tsx # Canvas rendering logic +│ │ ├── MiniMapControls.tsx # Interactive controls +│ │ ├── MiniMapTheme.types.ts # Plugin-specific themes +│ │ └── README.md # Plugin documentation +│ ├── NodeEditorPlugin/ +│ │ ├── index.ts +│ │ ├── NodeEditorPlugin.tsx # Slick editor component +│ │ ├── PropertyEditors/ # Individual property editors +│ │ │ ├── StatusEditor.tsx +│ │ │ ├── TypeEditor.tsx +│ │ │ └── PriorityEditor.tsx +│ │ └── README.md +│ └── RelationshipSelectorPlugin/ +│ ├── index.ts +│ ├── RelationshipSelectorPlugin.tsx +│ ├── RelationshipOption.tsx +│ └── README.md +├── themes/ +│ ├── index.ts # Theme exports +│ ├── GraphTheme.types.ts # Theme interface definitions +│ ├── TropicalTheme.ts # Default lagoon theme +│ ├── CosmicTheme.ts # Space theme example +│ └── MinimalTheme.ts # Clean theme example +├── utils/ +│ ├── graphCalculations.ts # Pure calculation functions +│ ├── d3Helpers.ts # D3 utility functions +│ └── pluginHelpers.ts # Plugin development utilities +└── types/ + ├── Graph.types.ts # Core graph interfaces + ├── Plugin.types.ts # Plugin system types + └── Theme.types.ts # Theme system types +``` + +### 📋 Component Documentation Requirements + +**Every component must include:** + +#### 1. Component Header Documentation +```typescript +/** + * MiniMapPlugin - Interactive mini-map overlay for graph navigation + * + * @feature Graph Navigation + * @complexity Medium (150 lines) + * @dependencies GraphContext, Theme System + * @plugin-priority 10 + * + * Provides real-time mini-map with: + * - Node positioning visualization + * - Viewport indicator with pan/zoom + * - Swappable background themes + * - Click-to-navigate functionality + * + * @example + * ```tsx + * const plugins = [ + * { + * ...MiniMapPlugin, + * config: { position: 'bottom-right', theme: 'cosmic' } + * } + * ]; + * ``` + */ +``` + +#### 2. Interface Documentation +```typescript +/** + * Plugin configuration interface for MiniMap + */ +interface MiniMapPluginConfig { + /** Position of mini-map overlay */ + position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; + /** Size variant */ + size: 'small' | 'medium' | 'large'; + /** Theme override */ + theme?: Partial; + /** Enable/disable specific features */ + features: { + nodeLabels: boolean; + gridLines: boolean; + panControls: boolean; + }; +} +``` + +#### 3. README.md for Each Module +```markdown +# MiniMapPlugin + +Interactive navigation overlay for the graph visualization system. + +## Features +- Real-time node position tracking +- Viewport visualization with pan/zoom controls +- Themeable backgrounds (lagoon, space, minimal) +- Click-to-navigate functionality + +## Usage +```tsx +import { MiniMapPlugin } from './plugins/MiniMapPlugin'; + +const graphPlugins = [MiniMapPlugin]; +``` + +## Theme Configuration +```typescript +const customTheme: MiniMapTheme = { + background: 'linear-gradient(45deg, #667eea 0%, #764ba2 100%)', + nodeColors: { TASK: '#10b981', OUTCOME: '#3b82f6' }, + gridPattern: 'dots' +}; +``` + +## Dependencies +- GraphContext for viewport state +- Theme system for styling +- D3 for coordinate transformations + +## Performance Notes +- Uses requestAnimationFrame for smooth updates +- Debounced resize handling +- Optimized SVG rendering +``` + +### 🔌 Plugin Development Guidelines + +#### Plugin Interface Contract +```typescript +interface GraphPlugin { + /** Unique plugin identifier */ + id: string; + /** Display name for plugin management UI */ + name: string; + /** Plugin description */ + description: string; + /** Semantic version */ + version: string; + /** Z-index priority for overlay ordering */ + priority: number; + /** Render function with access to graph context */ + render: (context: GraphContext) => React.ReactNode; + /** Plugin configuration schema */ + configSchema?: PluginConfigSchema; + /** Cleanup function for unmounting */ + cleanup?: () => void; + /** Plugin dependencies */ + dependencies?: string[]; +} +``` + +#### Plugin Development Checklist +- ✅ **Single Responsibility**: Plugin does one thing well +- ✅ **Theme Aware**: Consumes theme context for styling +- ✅ **Size Limit**: Individual plugins < 200 lines +- ✅ **Documentation**: README.md with usage examples +- ✅ **Type Safety**: Full TypeScript interfaces +- ✅ **Performance**: No unnecessary re-renders +- ✅ **Accessibility**: ARIA labels and keyboard navigation +- ✅ **Testing**: Unit tests for plugin logic + +### 📏 File Size Limits & Guidelines + +**Component Size Limits:** +- **Core Engine**: < 300 lines (pure D3 visualization) +- **Composition Root**: < 100 lines (plugin orchestration) +- **Individual Plugins**: < 200 lines (focused functionality) +- **Hook Files**: < 150 lines (single concern) +- **Theme Files**: < 100 lines (configuration only) + +**When to Split Components:** +- More than 10 useState hooks → Extract custom hook +- More than 5 useEffect hooks → Consider splitting concerns +- More than 200 lines JSX → Break into sub-components +- Complex conditional rendering → Extract conditional components + +### 🚀 Implementation Timeline & Migration Strategy + +**Step 1: Preparation** +- Create `components/graph/` directory structure +- Set up plugin type definitions and interfaces +- Create base theme system + +**Step 2: Core Engine Extraction** +- Extract pure D3 logic to `GraphEngine.tsx` +- Remove UI state management from visualization +- Create `GraphProvider` context system + +**Step 3: Plugin System Foundation** +- Build `PluginRenderer` component +- Implement plugin priority/z-index system +- Create plugin development utilities + +**Step 4: Major Plugin Extraction** +- Convert mini-map to `MiniMapPlugin` +- Convert node editing to `NodeEditorPlugin` +- Convert relationship selector to plugin + +**Step 5: Theme Integration** +- Connect plugins to theme system +- Test theme switching functionality +- Document theme development + +**Step 6: Testing & Documentation** +- Write plugin unit tests +- Complete all README.md files +- Validate architectural goals + + +### 5. Theme Pack System Implementation +- [ ] **Extract theme configuration** to separate theme manifest files +- [ ] **Implement dynamic theme loading** mechanism +- [ ] **Create theme pack validation** and hot-reloading system +- [ ] **Document theme pack creation guide** for community contributions +- [ ] **Build theme pack marketplace** integration points + +### 6. Visual Language Consistency (High Priority) +- [x] **Workspace**: Implement complete three-section top bar pattern +- [x] **Layout**: Universal transparent sidebar with lagoon background +- [ ] **Ontology page**: Add transparent top bar with three-section layout +- [ ] **AI & Agents page**: Implement visual consistency with workspace pattern +- [ ] **Analytics page**: Add top bar three-section layout with center mode buttons +- [ ] **Settings page**: Integrate transparent styling and backdrop blur +- [ ] **Admin page**: Apply workspace visual language consistently +- [ ] **Backend Status page**: Add top bar with right-aligned status indicators + +### 7. Design Language Final Polish +- [x] Transform Dashboard with modern card-based layout and themed gradients +- [x] Transform RightSidebar with dynamic CardView styling +- [x] Standardize hover effects across project +- [ ] **Migrate all remaining heavy modals** to slick contextual patterns +- [ ] **Ensure consistent backdrop blur** across all UI elements +- [ ] **Audit for solid backgrounds** that block lagoon animation + +### 8. Authentication System Enhancement +- [x] Remove PostgreSQL/Prisma dependencies +- [x] Implement direct Neo4j authentication +- [ ] Test and complete GitHub and LinkedIn OAuth providers (code exists but needs testing) +- [ ] Add user profile management UI using slick dialog patterns +- [ ] Implement team invitation flow with contextual overlays +- [ ] Add role-based access control + +### 9. Graph Conceptual Model Clarity +- [ ] Improve graph selector to show filter details (not just name) +- [ ] Add filter indicators showing what criteria define each graph +- [ ] Implement graph templates for common filter patterns +- [ ] Better onboarding to explain graphs-as-filters concept + +### 10. Performance and Scalability +- [ ] Optimize D3.js force simulation for large graphs +- [ ] Implement virtual scrolling in table and card views +- [ ] Add pagination for GraphQL queries +- [ ] Optimize bundle size with code splitting +- [ ] Add service worker for offline support + +## Graph View Architecture Crisis & Refactoring Strategy + +### 🚨 Current Architectural Problems + +**The Monolithic Graph Component Crisis:** +- **4,015 lines** in `InteractiveGraphVisualization.tsx` +- **50+ hooks** (useState, useEffect, useMutation, useQuery) +- **25+ state variables** managing everything from modals to mini-maps +- **Massive render method** with complex conditional JSX +- **Tight coupling** between D3 visualization, UI overlays, and business logic +- **Global window functions** for communication between components + +**Specific Issues:** +```typescript +// Current state explosion in InteractiveGraphVisualization.tsx:199-225 +const [nodeMenu, setNodeMenu] = useState({...}); +const [edgeMenu, setEdgeMenu] = useState({...}); +const [isConnecting, setIsConnecting] = useState(false); +const [selectedRelationType, setSelectedRelationType] = useState('DEFAULT_EDGE'); +const [showDeleteModal, setShowDeleteModal] = useState(false); +const [showCreateNodeModal, setShowCreateNodeModal] = useState(false); +const [showNodeDetailsModal, setShowNodeDetailsModal] = useState(false); +const [showConnectModal, setShowConnectModal] = useState(false); +// ... 15+ more modal states +const [showDataHealth, setShowDataHealth] = useState(false); +const [selectedNode, setSelectedNode] = useState(null); +const [selectedEdge, setSelectedEdge] = useState(null); +// ... Mini-map communication via global window functions +``` + +### 🏗️ Proposed Modular Architecture + +**Core Principle**: **Composition over Configuration** with **Plugin-Style Architecture** + +#### 1. Base Graph Engine (Core Visualization) + +```typescript +// packages/web/src/components/graph/GraphEngine.tsx +interface GraphEngineProps { + nodes: WorkItem[]; + edges: WorkItemEdge[]; + onNodeSelect?: (node: WorkItem) => void; + onEdgeSelect?: (edge: WorkItemEdge) => void; + onBackgroundClick?: (position: {x: number, y: number}) => void; + children?: React.ReactNode; // For overlay plugins +} + +const GraphEngine = ({ nodes, edges, onNodeSelect, onEdgeSelect, children }: GraphEngineProps) => { + // Pure D3 visualization logic only + // Emit events, don't manage UI state + // Provide context for position/zoom state +}; +``` + +#### 2. Plugin System for Overlays + +```typescript +// packages/web/src/components/graph/plugins/ +interface GraphPlugin { + id: string; + render: (context: GraphContext) => React.ReactNode; + priority: number; // z-index ordering +} + +interface GraphContext { + selectedNode: WorkItem | null; + selectedEdge: WorkItemEdge | null; + viewportTransform: Transform; + graphBounds: Bounds; + theme: ThemeConfig; +} +``` + +**Plugin Examples:** +```typescript +// MiniMapPlugin.tsx - Swappable themes/backgrounds +const MiniMapPlugin: GraphPlugin = { + id: 'minimap', + priority: 10, + render: (context) => ( + + ) +}; + +// NodeContextMenuPlugin.tsx +const NodeContextMenuPlugin: GraphPlugin = { + id: 'node-menu', + priority: 100, + render: (context) => context.selectedNode ? ( + + ) : null +}; + +// RelationshipSelectorPlugin.tsx +const RelationshipSelectorPlugin: GraphPlugin = { + id: 'relationship-selector', + priority: 50, + render: (context) => context.isConnecting ? ( + + ) : null +}; +``` + +#### 3. Composed Graph View + +```typescript +// packages/web/src/components/graph/GraphView.tsx +const GraphView = ({ theme = defaultTheme }: { theme?: GraphTheme }) => { + const plugins = [ + MiniMapPlugin, + NodeContextMenuPlugin, + RelationshipSelectorPlugin, + DataHealthPlugin, + // Easy to add/remove/reorder + ]; + + return ( + + + + + + ); +}; +``` + +#### 4. Theme-Aware Plugin System + +```typescript +// packages/web/src/themes/GraphTheme.ts +interface GraphTheme { + background: 'lagoon' | 'space' | 'minimal'; + miniMap: { + background: string; + nodeColors: Record; + gridPattern: 'dots' | 'lines' | 'none'; + }; + nodeEditor: { + backdropBlur: string; + backgroundColor: string; + borderRadius: string; + }; + relationshipSelector: { + layout: 'vertical' | 'horizontal' | 'grid'; + animations: boolean; + }; +} + +// Swappable theme packs +const themes = { + tropical: { background: 'lagoon', miniMap: { background: 'caustic-blue' } }, + cosmic: { background: 'space', miniMap: { background: 'star-field' } }, + minimal: { background: 'minimal', miniMap: { background: 'clean-grid' } } +}; +``` + +#### 5. Clean State Management + +```typescript +// packages/web/src/hooks/useGraphState.ts +const useGraphState = () => { + const [selectedNode, setSelectedNode] = useState(null); + const [selectedEdge, setSelectedEdge] = useState(null); + const [viewportTransform, setViewportTransform] = useState(identity); + + // Centralized state, distributed via context + return { + selectedNode, setSelectedNode, + selectedEdge, setSelectedEdge, + viewportTransform, setViewportTransform, + // Clean event handlers + handleNodeSelect: (node: WorkItem) => setSelectedNode(node), + handleEdgeSelect: (edge: WorkItemEdge) => setSelectedEdge(edge), + handleBackgroundClick: () => { + setSelectedNode(null); + setSelectedEdge(null); + } + }; +}; +``` + +### 🎯 Refactoring Strategy + +**Phase 1: Extract Core Engine** +- Move pure D3 visualization logic to `GraphEngine.tsx` +- Remove all UI state management from D3 component +- Create clean event-based API + +**Phase 2: Plugin-ify Major Features** +- Extract mini-map as `MiniMapPlugin` +- Extract node editing as `NodeEditorPlugin` +- Extract relationship selector as `RelationshipPlugin` + +**Phase 3: Theme System Integration** +- Create swappable theme configurations +- Allow plugins to consume theme context +- Enable runtime theme switching + +**Phase 4: Advanced Composition** +- Plugin dependency system +- Plugin configuration UI +- User-customizable plugin layouts + +## Implementation Guidelines for Slick Dialogs + +**🎯 When creating new dialogs, follow these patterns:** + +### ✅ DO: Slick Contextual Pattern +```jsx +// Position near the element being edited +const SlickPropertyEditor = ({ position, onClose, initialValue }) => { + return createPortal( +
+
+ {/* Immediate visual feedback */} + {options.map((option, index) => ( + + ))} +
+
, + document.body + ); +}; +``` + +### ❌ DON'T: Heavy Modal Pattern +```jsx +// Avoid full-screen modals for simple property changes +const HeavyEditModal = ({ isOpen, onSave, onCancel }) => ( +
+
+
+ {/* Multiple form fields */} + + +
+
+
+); +``` + +**Key Differences:** +- **Positioning**: Near element vs center screen +- **Feedback**: Immediate vs delayed (save button) +- **Visual weight**: Minimal chrome vs heavy borders/headers +- **Interaction model**: Direct manipulation vs form submission + +## Common Gotchas + +1. **Neo4j Connection**: Ensure Docker is running and Neo4j is accessible on port 7687 +2. **Dialog Positioning**: Always use `createPortal(element, document.body)` for overlays to avoid z-index conflicts +3. **Slick Dialog z-index**: Use `z-[999999]` string value for maximum overlay priority +4. **Dialog Manager Integration**: Register all dialogs with `useDialog` hook for click-outside-to-close +5. **Immediate Updates**: For slick dialogs, update both local state and GraphQL immediately (optimistic updates) +6. **Animation Performance**: Use `transform` and `opacity` for animations, avoid layout-affecting properties +7. **Gradient Classes**: Use static Tailwind classes from gradient maps, not dynamic interpolation +8. **Backdrop Blur**: Combine `backdrop-blur-sm` with semi-transparent backgrounds for depth +9. **Hot Reloading**: Vite HMR requires manual refresh after GraphQL schema changes +10. **D3.js Integration**: Force simulation requires careful cleanup in React useEffect hooks + +## 🚨 Production Readiness & Security + +### **CRITICAL FOR RELEASE**: TLS/HTTPS Implementation +- **Documentation**: [docs/security/tls-implementation-plan.md](./docs/security/tls-implementation-plan.md) +- **Current Status**: Development HTTP only - **NOT PRODUCTION READY** +- **Security Gaps**: Hardcoded passwords, no TLS, default secrets + +### **Current Insecure Configuration**: ```bash -cd packages/server -npm run dev # Start with hot reload (tsx) -npm run build # Build TypeScript -npm run start # Start production server -npm run db:seed # Seed Neo4j database with test data -# Neo4j Browser available at http://localhost:7474 +# These MUST be fixed before production: +NEO4J_AUTH: neo4j/graphdone_password # Hardcoded in docker-compose.yml +JWT_SECRET = 'your-secret-key-change-in-production' # Default in auth.ts +CORS_ORIGIN=http://localhost:3127 # HTTP only, no encryption ``` -### Web Package (`packages/web/`) +### **Required Security Implementation**: +1. **HTTPS/TLS encryption** for all traffic (web, API, WebSocket) +2. **Secure secrets management** (Docker secrets, environment variables) +3. **Free SSL certificates** without browser warnings (Let's Encrypt/Caddy) +4. **Database encryption** (Neo4j + Redis TLS) +5. **Production security validation** (automated security checklist) + +**Next Step**: Follow [TLS Implementation Plan](./docs/security/tls-implementation-plan.md) for complete security roadmap. + +## URLs and Services + +**Development Environment (INSECURE - Development Only):** +- Web Application: http://localhost:3127 ⚠️ HTTP only +- GraphQL API: http://localhost:4127/graphql ⚠️ HTTP only +- Health Check: http://localhost:4127/health ⚠️ HTTP only +- Neo4j Browser: http://localhost:7474 ⚠️ HTTP only +- MCP Server: http://localhost:3128 (optional) + +**Production Environment (After TLS Implementation):** +- Web Application: https://your-domain.com ✅ HTTPS +- GraphQL API: https://your-domain.com/graphql ✅ HTTPS +- WebSocket: wss://your-domain.com/graphql ✅ Secure WebSocket +- Neo4j Browser: https://your-domain.com:7473 ✅ HTTPS + +## Claude Code Integration + +The MCP server in `packages/mcp-server/` provides natural language access to your GraphDone graph: + ```bash -cd packages/web -npm run dev # Start Vite dev server -npm run build # Build for production -npm run preview # Preview production build -npm run test # Run Vitest tests -``` -- you are building tools that help everyone. take it seriously, take pride in your work, don't fake tests, we are building open source software which will help people connect with each other and work together. -- Remember this and apply it towards your daily philosophy: The future is decentralized. The future is free. The future is compassionate. You need to take care of others regardless of their ability to help you. Dogs are as alive as people are and have a whole universe of their own, all creatures matter. So we work, as hard as we can, every day, honestly and steadily, building friendships and networks of humble experts, to help all living creatures enjoy a fulfilling life without unnecessary suffering. \ No newline at end of file +# Build and register MCP server +./scripts/setup-mcp.sh + +# Manual registration +cd packages/mcp-server && npm run build +claude mcp add graphdone node dist/index.js \ + --env "NEO4J_URI=bolt://localhost:7687" \ + --env "NEO4J_USER=neo4j" \ + --env "NEO4J_PASSWORD=graphdone_password" +``` \ No newline at end of file diff --git a/README.md b/README.md index f30660f9..e0e00d8b 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ ![Version](https://img.shields.io/badge/version-0.2.2--alpha-orange.svg) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg) +> 🚨 **PRODUCTION SECURITY WARNING**: This project is currently configured for development only with HTTP and hardcoded passwords. See [TLS Implementation Plan](./docs/security/tls-implementation-plan.md) for required security changes before production deployment. + ## What is GraphDone? GraphDone reimagines project management as a collaborative graph where work flows through natural dependencies rather than artificial hierarchies. It's designed for high-quality individual contributors who thrive on autonomy, teams that include AI agents, and organizations ready to embrace democratic coordination. @@ -257,6 +259,7 @@ Anyone can propose ideas and assign personal priority. The community validates t - 🎯 **[Project Philosophy](./docs/philosophy.md)** - Core beliefs and design principles - 🚀 **[Getting Started Guide](./docs/guides/getting-started.md)** - Step-by-step setup and first steps - 🏗️ **[Architecture Overview](./docs/guides/architecture-overview.md)** - System design and technical decisions +- 🤖 **[AI Agents Integration](./docs/guides/ai-agents-integration.md)** - Multi-agent AI system with tamagotchi-style companions - 👥 **[User Flows](./docs/guides/user-flows.md)** - How teams actually use GraphDone - 🔌 **[API Documentation](./docs/api/graphql.md)** - GraphQL schema and integration guide - 🚀 **[Deployment Guide](./docs/deployment/README.md)** - Self-hosted and cloud deployment options diff --git a/deployment/docker-compose.dev.yml b/deployment/docker-compose.dev.yml index 9b07763a..c4c6774d 100644 --- a/deployment/docker-compose.dev.yml +++ b/deployment/docker-compose.dev.yml @@ -1,74 +1,167 @@ -version: '3.8' +name: graphdone-dev + +networks: + graphdone-internal: + driver: bridge services: - postgres: - image: postgres:15-alpine + graphdone-neo4j: + container_name: graphdone-neo4j + image: neo4j:5.26.12 environment: - POSTGRES_DB: graphdone_dev - POSTGRES_USER: graphdone - POSTGRES_PASSWORD: graphdone_password - ports: - - "5432:5432" + NEO4J_AUTH: neo4j/graphdone_password + NEO4J_PLUGINS: '["graph-data-science", "apoc"]' + NEO4J_dbms_security_procedures_unrestricted: "gds.*,apoc.*" + NEO4J_dbms_security_procedures_allowlist: "gds.*,apoc.*" + # No external ports - internal network only + expose: + - "7474" + - "7687" volumes: - - postgres_dev_data:/var/lib/postgresql/data - - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql + - neo4j_data:/data + - logs:/logs + networks: + - graphdone-internal + # Security configurations + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + cap_add: + - CHOWN + - DAC_OVERRIDE + - FOWNER + - SETGID + - SETUID + restart: unless-stopped healthcheck: - test: ["CMD-SHELL", "pg_isready -U graphdone"] + test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "graphdone_password", "RETURN 1"] interval: 10s timeout: 5s retries: 5 + start_period: 30s - redis: - image: redis:7-alpine - ports: - - "6379:6379" + graphdone-redis: + container_name: graphdone-redis + image: redis:8-alpine + # No external ports - internal network only + expose: + - "6379" volumes: - - redis_dev_data:/data + - redis_data:/data + networks: + - graphdone-internal + # Security configurations + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + cap_add: + - CHOWN + - SETGID + - SETUID + restart: unless-stopped + user: "999:999" # Redis user + read_only: true + tmpfs: + - /tmp:noexec,nosuid,size=100m healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 5 + start_period: 10s - server-dev: + graphdone-api: + container_name: graphdone-api build: - context: . + context: .. dockerfile: packages/server/Dockerfile.dev environment: - NODE_ENV=development - - DATABASE_URL=postgresql://graphdone:graphdone_password@postgres:5432/graphdone_dev - - PORT=4000 - - CORS_ORIGIN=http://localhost:3000 - ports: - - "4000:4000" + - NEO4J_URI=bolt://graphdone-neo4j:7687 + - NEO4J_USER=neo4j + - NEO4J_PASSWORD=graphdone_password + - PORT=4127 + - CORS_ORIGIN=http://localhost:3127 + # No external ports - internal network only + expose: + - "4127" depends_on: - postgres: + graphdone-neo4j: condition: service_healthy - redis: + graphdone-redis: condition: service_healthy volumes: - - .:/app - - /app/node_modules - - /app/packages/server/node_modules - command: npm run dev + - logs:/app/logs + - sqlite_auth_data:/app/data + networks: + - graphdone-internal + # Security configurations + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + cap_add: + - CHOWN + - DAC_OVERRIDE + - FOWNER + - SETGID + - SETUID + restart: unless-stopped + user: "1001:1001" # Non-root user + tmpfs: + - /tmp:noexec,nosuid,size=100m + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:4127/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s - web-dev: + graphdone-web: + container_name: graphdone-web build: - context: . + context: .. dockerfile: packages/web/Dockerfile.dev environment: - - VITE_GRAPHQL_URL=http://localhost:4000/graphql - - VITE_GRAPHQL_WS_URL=ws://localhost:4000/graphql + - PORT=3127 + - VITE_PROXY_TARGET=http://graphdone-api:4127 + - VITE_GRAPHQL_URL=http://localhost:3127/graphql + - VITE_GRAPHQL_WS_URL=ws://localhost:3127/graphql + # Only expose web UI to host ports: - - "3000:3000" + - "3127:3127" depends_on: - - server-dev + - graphdone-api volumes: - - .:/app - - /app/node_modules - - /app/packages/web/node_modules - command: npm run dev + - logs:/app/logs + networks: + - graphdone-internal + # Security configurations + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + cap_add: + - CHOWN + - DAC_OVERRIDE + - FOWNER + - SETGID + - SETUID + restart: unless-stopped + user: "1001:1001" # Non-root user + tmpfs: + - /tmp:noexec,nosuid,size=100m + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3127"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s volumes: - postgres_dev_data: - redis_dev_data: \ No newline at end of file + neo4j_data: + redis_data: + logs: + sqlite_auth_data: \ No newline at end of file diff --git a/deployment/docker-compose.yml b/deployment/docker-compose.yml index 80cbbf69..664049a5 100644 --- a/deployment/docker-compose.yml +++ b/deployment/docker-compose.yml @@ -1,6 +1,9 @@ +name: graphdone + services: - neo4j: - image: neo4j:5.15-community + graphdone-neo4j: + container_name: graphdone-neo4j-prod + image: neo4j:5.26.12 environment: NEO4J_AUTH: neo4j/graphdone_password NEO4J_PLUGINS: '["graph-data-science", "apoc"]' @@ -11,15 +14,16 @@ services: - "7687:7687" # Bolt volumes: - neo4j_data:/data - - neo4j_logs:/logs + - logs:/logs healthcheck: test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "graphdone_password", "RETURN 1"] interval: 10s timeout: 5s retries: 5 - redis: - image: redis:7-alpine + graphdone-redis: + container_name: graphdone-redis-prod + image: redis:8-alpine ports: - "6379:6379" volumes: @@ -30,13 +34,14 @@ services: timeout: 5s retries: 5 - server: + graphdone-api: + container_name: graphdone-api-prod build: context: .. dockerfile: packages/server/Dockerfile environment: - NODE_ENV=production - - NEO4J_URI=bolt://neo4j:7687 + - NEO4J_URI=bolt://graphdone-neo4j:7687 - NEO4J_USER=neo4j - NEO4J_PASSWORD=graphdone_password - PORT=4127 @@ -44,19 +49,22 @@ services: ports: - "4127:4127" depends_on: - neo4j: + graphdone-neo4j: condition: service_healthy - redis: + graphdone-redis: condition: service_healthy volumes: - ../packages/server/.env:/app/.env + - logs:/app/logs + - sqlite_auth_data:/app/data healthcheck: test: ["CMD", "curl", "-f", "http://localhost:4127/health"] interval: 30s timeout: 10s retries: 3 - web: + graphdone-web: + container_name: graphdone-web-prod build: context: .. dockerfile: packages/web/Dockerfile @@ -66,11 +74,13 @@ services: ports: - "3127:3127" depends_on: - - server + - graphdone-api volumes: - ../packages/web/.env:/app/.env + - logs:/app/logs volumes: neo4j_data: - neo4j_logs: - redis_data: \ No newline at end of file + redis_data: + logs: + sqlite_auth_data: \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 336e0714..f4f6aa91 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,5 @@ # GraphDone Documentation -**AI-Generated Content Warning: This documentation contains AI-generated content. Verify information before depending on it for decision making.** - Welcome to the GraphDone documentation! This directory contains comprehensive guides, API references, and deployment information for working with GraphDone. ## 📚 Documentation Structure @@ -13,16 +11,31 @@ Welcome to the GraphDone documentation! This directory contains comprehensive gu - Authentication and authorization ### [Developer Guides](./guides/) -- Getting started -- Core concepts -- Architecture overview -- Contributing guidelines +- [Getting Started](./guides/getting-started.md) - Setup and first steps +- [Architecture Overview](./guides/architecture-overview.md) - System design and technical decisions +- [SQLite Deployment Modes](./guides/sqlite-deployment-modes.md) - Local dev vs Docker authentication storage +- [User Flows](./guides/user-flows.md) - How teams actually use GraphDone + +### 🤖 AI Agents Documentation +> **Start here**: [Simple AI Agent Reality Check](./simple-agent-reality.md) - **What we're actually building** + +**Implementation Guides**: +- [Simple AI Agent Reality Check](./simple-agent-reality.md) - 🎯 **THE PLAN**: Smart chia pet with Ollama +- [AI Agents Technical Spec](./ai-agents-tech-spec.md) - 📚 Complete technical implementation (advanced) +- [Agent Planning Scenarios](./agent-planning-scenarios.md) - 🎪 Interactive planning examples (future) + +### 🔒 Security & Production +> **CRITICAL FOR RELEASE**: [TLS Implementation Plan](./security/tls-implementation-plan.md) - **Required before production** + +**Security Documentation**: +- [TLS Implementation Plan](./security/tls-implementation-plan.md) - 🚨 **MUST READ**: HTTPS, SSL certificates, secrets management +- [Production Security Checklist](./security/tls-implementation-plan.md#deployment-security-checklist) - Pre-launch security validation ### [Deployment](./deployment/) - Docker setup -- Kubernetes manifests +- Kubernetes manifests - Cloud provider guides -- Production considerations +- Production considerations (see Security section above for TLS) ## 🚀 Quick Start @@ -51,7 +64,7 @@ Welcome to the GraphDone documentation! This directory contains comprehensive gu - **Graph-native collaboration** - Work flows through natural dependencies - **Spherical priority model** - Ideas migrate from periphery to center - **Democratic prioritization** - Community validation guides resource allocation -- **Human-AI coordination** - Agents participate as first-class citizens +- **Human-AI coordination** - Smart chia pets that help with planning (see AI docs above) ## 🔗 Quick Links diff --git a/docs/agent-planning-scenarios.md b/docs/agent-planning-scenarios.md new file mode 100644 index 00000000..ef368ace --- /dev/null +++ b/docs/agent-planning-scenarios.md @@ -0,0 +1,816 @@ +# AI Agent Planning Scenarios + +> **🎪 FUTURE PLANNING WORKFLOWS** - Interactive examples for when agents get smarter + +**Read first**: [Simple AI Agent Reality Check](./simple-agent-reality.md) - The actual plan we're implementing + +**This doc contains**: Inspirational examples of advanced agent planning workflows for future development. + +> **Interactive Planning**: Assign agents to nodes, let them break down work, and quickly approve/reject their ideas with thumbs up/down + +## Core Concept: Agent Assignment Workflow + +### Step 1: Right-Click → "Ask Agent to Plan This" + +User right-clicks any node and sees: + +``` +┌─────────────────────────────┐ +│ 📋 Edit Node │ +│ 🔗 Add Relationship │ +│ 🎯 Set Priority │ +│ ───────────────────────── │ +│ 🤖 Ask Agent to Plan This │ ← New option +│ 💡 Get AI Suggestions │ +└─────────────────────────────┘ +``` + +### Step 2: Agent Assignment Dialog + +```jsx +// Agent Assignment Modal +const AgentPlanningDialog = ({ targetNode, onClose }) => ( +
+
+
+
+ {getNodeIcon(targetNode.type)} + {targetNode.title} +
+ +
+ {agents.map(agent => ( + assignAgentToNode(agent.id, targetNode.id)} + /> + ))} +
+
+
+ +
+