Skip to content

Commit fca9406

Browse files
author
Matthew Valancy
committed
Add project development guidelines and instructions
- CLAUDE.md with project overview and development commands - Technology stack and architecture documentation - Development workflow and testing approach - Current implementation status and roadmap - Guidelines for Claude Code assistance
1 parent 024a035 commit fca9406

1 file changed

Lines changed: 275 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
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.1.0-alpha) with core architecture implemented and working foundation.
8+
9+
## Core Philosophy
10+
11+
- Work flows through natural dependencies, not artificial hierarchies
12+
- Ideas migrate from periphery to center based on community validation and democratic prioritization
13+
- Human and AI agents collaborate as peers through the same graph interface
14+
- Designed for neurodivergent individuals and those who think differently about work
15+
16+
## Planned Architecture
17+
18+
### Technology Stack
19+
- **Frontend**: React 18 with TypeScript, React Native for mobile, D3.js for graph visualization
20+
- **Backend**: Node.js with TypeScript, GraphQL with Apollo Server, PostgreSQL with graph extensions
21+
- **State Management**: Zustand
22+
- **Styling**: Tailwind CSS
23+
- **Build Tool**: Vite
24+
- **Real-time**: WebSocket subscriptions
25+
- **Infrastructure**: Docker, Kubernetes, GitHub Actions for CI/CD
26+
27+
### Project Structure (Implemented)
28+
```
29+
packages/
30+
├── core/ # Graph engine and algorithms (✅ Complete)
31+
├── web/ # React web application (✅ Complete)
32+
├── server/ # GraphQL API server (✅ Complete)
33+
└── agent-sdk/ # SDK for AI agent integration (🔄 Planned)
34+
35+
Additional:
36+
├── docs/ # Comprehensive documentation
37+
├── scripts/ # Development and deployment scripts
38+
└── .github/ # CI/CD workflows
39+
```
40+
41+
## Development Commands
42+
43+
The project has a fully implemented monorepo structure with these commands:
44+
45+
```bash
46+
# Quick setup (recommended)
47+
./setup.sh # Complete environment setup
48+
./run.sh # Start all development servers
49+
50+
# Manual setup
51+
npm install # Install dependencies
52+
cp .env.example .env # Create environment file
53+
docker-compose up -d postgres # Start PostgreSQL
54+
npm run db:migrate # Run database migrations
55+
56+
# Development
57+
npm run dev # Start all development servers (Turbo)
58+
npm run test # Run all tests
59+
npm run lint # Lint all packages
60+
npm run typecheck # Type check all packages
61+
npm run build # Build all packages
62+
63+
# Database operations
64+
npm run db:migrate # Run Prisma migrations
65+
npm run db:seed # Seed database with test data
66+
67+
# Docker development
68+
docker-compose -f docker-compose.dev.yml up # With hot reload
69+
docker-compose up # Production-like environment
70+
```
71+
72+
## Key Concepts
73+
74+
### Graph Structure
75+
- **Nodes**: Outcomes, tasks, milestones, contributors (human and AI)
76+
- **Edges**: Dependencies, relationships, priorities
77+
- **Spherical Coordinates**: 3D positioning based on priority (center = highest priority)
78+
79+
### Priority System
80+
- Executive flags create gravity wells but don't control entire structure
81+
- Individual contributors can establish small gravity wells on periphery
82+
- Anonymous democratic rating system for idea validation
83+
- Priority determines resource allocation and position in spherical model
84+
85+
### Agent Integration
86+
Agents are first-class citizens that:
87+
- Read/write graph state through standard GraphQL endpoints
88+
- Receive real-time notifications for graph changes
89+
- Request compute resources based on node priority
90+
- Coordinate with humans through the same interface
91+
92+
## Implementation Guidelines
93+
94+
When implementing features:
95+
96+
1. **Graph-First Design**: All features should work within the graph paradigm
97+
2. **Mobile-First UI**: Touch interactions must be primary, not an afterthought
98+
3. **Agent Parity**: Any action a human can take, an agent should be able to take via API
99+
4. **Democratic by Default**: Community validation mechanisms should be built into core features
100+
5. **Accessibility**: Design for neurodiversity and different cognitive styles
101+
102+
## Development Commands
103+
104+
```bash
105+
# Initial setup
106+
./setup.sh # Set up development environment
107+
./run.sh # Start development servers
108+
./test.sh # Run test suite with linting and type checking
109+
./build.sh # Build all packages
110+
./deploy.sh # Deploy to staging/production
111+
./document.sh # Generate and deploy documentation
112+
113+
# Docker development
114+
./run.sh --docker-dev # Start with Docker (development)
115+
./run.sh --docker # Start with Docker (production)
116+
117+
# Package-specific testing
118+
./test.sh --package core # Test specific package
119+
./test.sh --coverage # Run with coverage report
120+
./test.sh --watch # Run in watch mode
121+
122+
# Turbo commands (alternative)
123+
npm run dev # Start all development servers
124+
npm run build # Build all packages
125+
npm run test # Run all tests
126+
npm run lint # Lint all packages
127+
npm run typecheck # Type check all packages
128+
```
129+
130+
## Current Implementation Status
131+
132+
✅ **Completed:**
133+
- Monorepo structure with Turbo for build orchestration
134+
- Core graph engine with Node, Edge, Priority calculation, and full graph operations
135+
- GraphQL API server with comprehensive schema and resolvers
136+
- React web application with D3.js graph visualization
137+
- TypeScript configuration across all packages
138+
- Vitest testing infrastructure with sample tests
139+
- Docker development and production configurations
140+
- Development scripts for setup, running, testing, building, and deployment
141+
- GitHub Actions CI/CD workflows for testing, building, and deployment
142+
- Comprehensive documentation structure
143+
144+
🏗️ **Architecture Implemented:**
145+
- `packages/core/` - Graph engine with priority calculation, node/edge management, path finding, cycle detection
146+
- `packages/server/` - GraphQL API with Prisma database schema, Apollo Server, WebSocket subscriptions
147+
- `packages/web/` - React app with Vite, Tailwind CSS, D3.js visualization, GraphQL client
148+
- Docker configurations for development and production
149+
- Kubernetes-ready manifests (planned in deployment docs)
150+
- Full CI/CD pipeline with testing, security scanning, and deployment
151+
152+
🎯 **Ready for Development:**
153+
All foundation pieces are in place. To continue development:
154+
1. Run `./setup.sh` to initialize the development environment
155+
2. Use `./run.sh` to start development servers
156+
3. Access the working application at http://localhost:3000
157+
4. Use GraphQL Playground at http://localhost:4000/graphql
158+
5. Begin implementing specific features using the established patterns
159+
6. Add more comprehensive tests using the Vitest setup
160+
7. Enhance the GraphQL schema and resolvers as needed
161+
162+
## Core Architecture
163+
164+
### Graph Engine (`packages/core/`)
165+
The heart of GraphDone is a custom graph engine with these key classes:
166+
167+
- **Graph**: Main graph container with nodes/edges, adjacency lists, pathfinding, cycle detection
168+
- **Node**: Individual graph nodes with priority calculation, spherical positioning
169+
- **Edge**: Connections between nodes with types (DEPENDENCY, BLOCKS, etc.)
170+
- **Priority**: Multi-dimensional priority system (executive, individual, community)
171+
- **PriorityCalculator**: Algorithms for computing weighted priorities and spherical positions
172+
173+
Key files:
174+
- `packages/core/src/graph.ts` - Main Graph class with all operations
175+
- `packages/core/src/node.ts` - Node implementation with priority management
176+
- `packages/core/src/priority.ts` - Priority calculation logic
177+
- `packages/core/src/types.ts` - TypeScript definitions
178+
179+
### GraphQL API (`packages/server/`)
180+
Apollo Server with real-time subscriptions:
181+
182+
- **Database**: PostgreSQL with Prisma ORM
183+
- **Schema**: Comprehensive GraphQL schema matching core types
184+
- **Resolvers**: CRUD operations for nodes, edges, contributors
185+
- **Subscriptions**: Real-time WebSocket updates
186+
- **Health Check**: `/health` endpoint for monitoring
187+
188+
Key files:
189+
- `packages/server/src/index.ts` - Apollo Server setup with WebSocket support
190+
- `packages/server/src/schema/index.ts` - GraphQL type definitions
191+
- `packages/server/src/resolvers/` - GraphQL resolvers
192+
- `packages/server/prisma/schema.prisma` - Database schema
193+
194+
### Web Application (`packages/web/`)
195+
React app with D3.js visualization:
196+
197+
- **Framework**: React 18 + TypeScript + Vite
198+
- **Styling**: Tailwind CSS
199+
- **Visualization**: D3.js for interactive graph rendering
200+
- **State**: Apollo Client for GraphQL state management
201+
- **Routing**: React Router for navigation
202+
203+
Key files:
204+
- `packages/web/src/App.tsx` - Main application router
205+
- `packages/web/src/components/GraphVisualization.tsx` - D3.js graph component
206+
- `packages/web/src/lib/apollo.ts` - GraphQL client configuration
207+
208+
## Testing Strategy
209+
210+
All packages use Vitest for testing:
211+
212+
```bash
213+
# Run all tests
214+
npm run test
215+
216+
# Run specific package tests
217+
npm run test --filter=@graphdone/core
218+
npm run test --filter=@graphdone/server
219+
npm run test --filter=@graphdone/web
220+
221+
# Run with coverage
222+
npm run test -- --coverage
223+
```
224+
225+
Current test files:
226+
- `packages/core/tests/` - Graph engine unit tests
227+
- `packages/server/tests/` - API integration tests
228+
- `packages/web/src/test/` - React component tests
229+
230+
## Database Schema
231+
232+
PostgreSQL with these main tables:
233+
- **Node**: Graph nodes with spherical coordinates and priorities
234+
- **Edge**: Connections between nodes with types and weights
235+
- **Contributor**: Users and AI agents in the system
236+
- **NodeContributor**: Many-to-many relationship
237+
238+
Key database operations:
239+
```bash
240+
npm run db:migrate # Apply schema changes
241+
npm run db:seed # Add test data
242+
npm run db:studio # Open Prisma Studio GUI
243+
```
244+
245+
## Package-Specific Commands
246+
247+
### Core Package (`packages/core/`)
248+
```bash
249+
cd packages/core
250+
npm run build # Build TypeScript
251+
npm run dev # Watch mode
252+
npm run test # Run Vitest tests
253+
npm run lint # ESLint
254+
npm run typecheck # TypeScript check
255+
```
256+
257+
### Server Package (`packages/server/`)
258+
```bash
259+
cd packages/server
260+
npm run dev # Start with hot reload (tsx)
261+
npm run build # Build TypeScript
262+
npm run start # Start production server
263+
npm run db:migrate # Run Prisma migrations
264+
npm run db:seed # Seed test data
265+
npm run db:studio # Open Prisma Studio
266+
```
267+
268+
### Web Package (`packages/web/`)
269+
```bash
270+
cd packages/web
271+
npm run dev # Start Vite dev server
272+
npm run build # Build for production
273+
npm run preview # Preview production build
274+
npm run test # Run Vitest tests
275+
```

0 commit comments

Comments
 (0)