LifeBuild

LifeBuild is a visual life management system. You map your personal life across eight domains, see all your projects in one place, prioritize ruthlessly, and delegate the operational stuff to AI workers who actually do things.

The premise: your personal life deserves the same strategic clarity you bring to your best professional work.

Read some of the thinking behind the technical foundations underpinning LifeBuild.

Building in Public

Check out our development plans to see what we're working on and where we're headed. I've been using AI to build this as well, and the plans are an interesting artifact of that process.

Project Management

We track work using GitHub Issues and the SocioTechnica Project Board.

• Projects: Timebound, goal-oriented work efforts tracked as GitHub Issues with type "Project"
• Sub-issues: Individual tasks linked to parent Project issues
• Cross-repo: Projects can contain issues from any repository in the organization

Creating a New Project

Create a new GitHub Issue in the lifebuild repo with:

• Issue type: Project
• Title format: Project: [Name]
• Body: Include a Goal and Success Criteria

Adding Issues to a Project

1. Navigate to the Project issue (e.g., #410)
2. In the right sidebar, find Sub-issues
3. Click Add sub-issue to link existing issues or create new ones

Adding Issues to Current Iteration

1. Go to the All Items view in the Project Board
2. Find the issue you want to add
3. Set the Iteration field to the current iteration

See CLAUDE.md for CLI commands and detailed workflows.

Monorepo Structure

This project is organized as a pnpm workspace with the following packages:

• packages/web - React frontend application
• packages/worker - Cloudflare Worker backend for WebSocket sync
• packages/server - Node.js server for LLM processing
• packages/auth-worker - JWT authentication service
• packages/shared - Shared schemas and utilities

Quick Start

1. Install dependencies:

   pnpm install
   

2. Set up environment variables: Copy the environment files:

   cp packages/web/.env.example packages/web/.env
   cp packages/worker/.dev.vars.example packages/worker/.dev.vars
   cp packages/auth-worker/.dev.vars.example packages/auth-worker/.dev.vars
   cp packages/server/.env.example packages/server/.env
   

   Update the environment files with your specific values:

   • packages/web/.env - Frontend configuration
   • packages/worker/.dev.vars - Main worker with Braintrust API credentials
   • packages/auth-worker/.dev.vars - Authentication service
   • packages/server/.env - Server configuration

   Update packages/worker/.dev.vars with:

   ENVIRONMENT=development
   REQUIRE_AUTH=false
   JWT_SECRET=dev-jwt-secret-change-me-in-production
   GRACE_PERIOD_SECONDS=86400
   SERVER_BYPASS_TOKEN=dev-server-bypass-token-change-me
   BRAINTRUST_API_KEY="your-braintrust-api-key-here"
   BRAINTRUST_PROJECT_ID="your-braintrust-project-id-here"
   

   Update packages/auth-worker/.dev.vars with:

   ENVIRONMENT=development
   JWT_SECRET=dev-jwt-secret-change-me-in-production
   

   (Get Braintrust credentials from https://www.braintrust.dev/)

3. Run the development server: This will start the Vite frontend and Cloudflare Worker concurrently.

   pnpm dev
   

   To run on a custom port:

   PORT=3000 VITE_LIVESTORE_SYNC_URL='http://localhost:8787' pnpm dev
   

Deployment

LifeBuild uses a separated deployment architecture with three services:

• Web Frontend: Deployed to Cloudflare Pages at app.lifebuild.me
• WebSocket Sync: Cloudflare Worker at sync.lifebuild.me
• Authentication: Cloudflare Worker at auth.lifebuild.me

Automated Deployment

All services are automatically deployed upon every push to the main branch using GitHub Actions:

1. Auth Worker → Cloudflare Workers
2. Sync Worker → Cloudflare Workers
3. Web App → Cloudflare Pages

Manual Deployment

To deploy individual services manually (requires wrangler authentication):

# Deploy all services
pnpm --filter @lifebuild/auth-worker run deploy  # Auth service
pnpm --filter @lifebuild/worker run deploy       # Sync server
pnpm --filter @lifebuild/web run deploy          # Frontend to Pages

# Or deploy specific service
pnpm --filter @lifebuild/web run deploy         # Just the web app

First-Time Setup

Before the first deployment, you need to create the production D1 database and configure its ID.

1. Run the following command to create the database on Cloudflare:

   pnpm --filter @lifebuild/worker wrangler d1 create lifebuild-prod
   

2. Copy the database_id from the command's output.

3. Open packages/worker/wrangler.jsonc and paste the copied ID into the database_id field within the d1_databases section.

Features

• Life Map: Dashboard view of all eight life domains with active projects, progress, and backlogs at a glance
• Drafting Room: Three-stage planning pipeline (Identify, Scope, Detail) to turn ideas into well-defined projects
• Sorting Room: Prioritize across Gold, Silver, and Bronze streams — activate projects to "The Table" and manage your backlog
• Project Room: Per-project workspace with kanban task board, drag-and-drop, and room-based chat
• AI Workers: Delegate operational work to LLM-powered agents that take action inside your projects
• Local-first Architecture: Works offline with automatic sync, powered by LiveStore event sourcing

Git Hooks

A pre-push hook (via Husky) runs pnpm format:check before every push. If any files aren't formatted, the push is blocked. Run pnpm lint-all to fix formatting, then push again.

To skip the hook when needed:

git push --no-verify

Development Commands

Workspace Commands (run from root)

# Development
pnpm dev              # Start all services (web + worker + server)
pnpm dev:web          # Start only frontend
pnpm dev:worker       # Start only sync worker
pnpm dev:server       # Start only Node.js server
pnpm dev:auth         # Start only auth service

# Quality Checks (all packages)
pnpm lint-all         # Run linting, formatting, and type checking
pnpm typecheck        # Type check all packages
pnpm lint:fix         # Auto-fix linting issues
pnpm format           # Format code

# Testing
pnpm test                  # Run unit tests (web + auth)
pnpm test:watch            # Run tests in watch mode
pnpm test:e2e              # Run E2E tests
pnpm test:e2e:ui           # Run E2E tests with UI
pnpm test:integration:auth # Run auth service integration tests

# Building & Deployment
pnpm build            # Build all packages
pnpm deploy:worker    # Deploy sync worker to Cloudflare
pnpm deploy:auth      # Deploy auth service to Cloudflare

Package-specific Commands

All packages support a consistent set of scripts where applicable:

# Quality checks (available in packages with source code)
pnpm --filter <package> lint-all    # Complete quality check
pnpm --filter <package> typecheck   # TypeScript type checking
pnpm --filter <package> lint        # Run linter
pnpm --filter <package> lint:fix    # Auto-fix linting issues
pnpm --filter <package> format      # Format code

# Testing (available in packages with tests)
pnpm --filter <package> test        # Run tests once
pnpm --filter <package> test:watch  # Run tests in watch mode

# Development
pnpm --filter <package> dev         # Start development server
pnpm --filter <package> build       # Build for production

Script Standards

Each package follows consistent naming conventions:

Script	Purpose	Available In
dev	Development server	web, worker, server, auth-worker
build	Production build	web, server
test	Run tests once	web, auth-worker
test:watch	Watch mode tests	web, auth-worker
lint-all	All quality checks	All packages
typecheck	TypeScript checking	All packages
lint	Linting only	web, server
lint:fix	Auto-fix linting	web, server
format	Code formatting	web, server

Ports

• Vite dev server: 60001 (default), configurable via PORT environment variable
• Cloudflare Worker: 8787 (WebSocket sync server)
• Auth Worker: 8788 (JWT authentication service)
• Node.js Server: 3001 (LLM processing server)
• Storybook: 6010 (configured to avoid conflicts with other Storybook instances)

Testing

The project includes a comprehensive testing setup:

Unit & Component Tests (Vitest + React Testing Library)

pnpm test              # Run all tests
pnpm test:watch        # Run tests in watch mode
pnpm test:coverage     # Generate coverage report

Component Development (Storybook)

pnpm storybook         # Start Storybook dev server (port 6010)
pnpm build-storybook   # Build static Storybook
pnpm test:storybook    # Run Storybook tests

CI/CD

• All tests run automatically on every PR via GitHub Actions
• Test results and coverage reports are uploaded as artifacts

Architecture

LifeBuild is built with a modern monorepo architecture featuring real-time collaboration and AI integration.

📖 For detailed technical architecture, see docs/architecture.md

Key Technologies

• Monorepo: pnpm workspaces with TypeScript across all packages
• Frontend: React 19, Vite, Tailwind CSS, LiveStore for state management
• Backend: Cloudflare Worker with Durable Objects and WebSocket sync
• AI Integration: Client-side agentic loops with tool calling via LLM proxy
• Testing: Vitest, React Testing Library, Playwright E2E tests