ProjectE/README.md

Project E

A personal project, habit, and task tracker built for the AI-agent era. Track tasks, build habits, manage projects, write notes, generate reports, and let AI agents work alongside you through a native MCP (Model Context Protocol) server.

Features

• Tasks: Kanban boards, priorities, due dates, subtasks, time tracking, recurring tasks, dependencies, and attachments
• Habits: Daily/weekly/custom frequencies, streak tracking, mood logging, skip days, and completion scoring
• Projects: Organize work by domain, track progress through milestones, set deadlines, and manage team members
• Notes: Rich text editor with wikilinks, note graph visualization, bookmarks, and AI-generated content support
• Reports: Weekly, monthly, project, and habit reports with templates and AI-assisted generation
• Milestones: Plan project phases, set dependencies, and track completion
• Domains & Tags: Organize everything across life domains (work, personal, health) with flexible tagging
• AI Agents: Register agents with API keys, assign permission tiers, and dispatch work via @mentions
• Webhooks: Subscribe to events, deliver payloads with HMAC signatures, and track delivery history
• Analytics: Task completion rates, habit consistency, time summaries, and streak tracking
• Realtime: Server-sent events proxy keeps the UI in sync across devices
• Background Worker: Processes webhook deliveries, agent mentions, report generation, recurring tasks, and data cleanup
• MCP Server: 61 tools for AI agents to read and write data through the Model Context Protocol

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Frontend (Next.js)                      │
│  React 19 · App Router · shadcn/ui · Tailwind · Zustand     │
└──────────────────────────┬──────────────────────────────────┘
                           │ REST API + SSE
┌──────────────────────────▼──────────────────────────────────┐
│                   API Layer (Next.js Routes)                  │
│  Auth · Validation (Zod) · Realtime SSE Proxy · MCP Server  │
└──────────────────────────┬──────────────────────────────────┘
                           │ PocketBase SDK
┌──────────────────────────▼──────────────────────────────────┐
│                   Data Layer (PocketBase)                     │
│  SQLite · Auth · Realtime · File Storage · Admin UI          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Background Worker                          │
│  Webhook Delivery · Agent Mentions · Report Generation       │
│  Recurring Tasks · Data Cleanup                              │
└─────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Frontend	Next.js 15, React 19, TypeScript 5.9
UI Components	shadcn/ui, Radix UI, Lucide icons
Styling	Tailwind CSS 3.4, tailwind-merge, class-variance-authority
State Management	Zustand 5 (UI), PocketBase realtime (data)
Rich Text	Tiptap 3
Forms	React Hook Form 7, Zod 4 validation
Calendar	react-big-calendar, date-fns
Charts	Recharts 3
Graph Visualization	react-force-graph-2d
Drag & Drop	@dnd-kit
Backend	Next.js API routes (App Router)
Database	PocketBase 0.25 (SQLite)
Background Jobs	Node.js worker with polling and exponential backoff
MCP Server	@modelcontextprotocol/sdk 1.29
Monorepo	Turborepo 2.5, npm workspaces
Testing	Jest (unit/component), Playwright 1.61 (E2E)
Deployment	Docker Compose (3 containers)

Prerequisites

• Node.js 22.13.0 or later
• npm 10.0.0 or later
• Docker and Docker Compose (for production deployment)
• PocketBase 0.25.5 (included in Docker setup)

Quick Start

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd ProjectE
   

2. Install dependencies

   npm install
   

3. Start PocketBase (in a separate terminal)

   # Download PocketBase if you haven't already
   # https://pocketbase.io/docs/
   
   # Start PocketBase with migrations
   pocketbase serve --dir=./pb_data --publicDir=./pb_public --migrationDir=./pocketbase/pb_migrations
   

   Or use Docker:

   docker compose up db -d
   

4. Set environment variables

   Create a .env.local file in the root:

   POCKETBASE_URL=http://localhost:8090
   POCKETBASE_ADMIN_TOKEN=your_admin_token_here
   

   Get the admin token from PocketBase after creating your first admin account.

5. Start the development server

   npm run dev
   

   This starts all packages via Turborepo:

   • Web app at http://localhost:3000
   • PocketBase at http://localhost:8090
   • Worker (if configured)

6. Create your first user

   Open http://localhost:3000 and sign up, or use the PocketBase admin UI at http://localhost:8090/_/ to create users.

Production Deployment (Docker)

# Build and start all containers
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Stop all containers
docker compose down

The deployment starts three containers:

• web: Next.js app on port 3000
• db: PocketBase on port 8090
• worker: Background job processor

Project Structure

project-e/
├── apps/
│   └── web/                    # Next.js application
│       ├── app/                # App Router pages and API routes
│       │   ├── (auth)/         # Auth pages (login, signup)
│       │   ├── (dashboard)/    # Dashboard pages
│       │   ├── api/            # REST API endpoints
│       │   │   ├── auth/       # Login, logout, refresh, me
│       │   │   ├── tasks/      # Task CRUD + bulk operations
│       │   │   ├── habits/     # Habit CRUD
│       │   │   ├── projects/   # Project CRUD
│       │   │   ├── notes/      # Note CRUD
│       │   │   ├── reports/    # Report CRUD
│       │   │   ├── milestones/ # Milestone CRUD
│       │   │   ├── domains/    # Domain CRUD
│       │   │   ├── tags/       # Tag CRUD
│       │   │   ├── agents/     # Agent CRUD
│       │   │   ├── webhooks/   # Webhook CRUD
│       │   │   ├── analytics/  # Analytics data
│       │   │   ├── realtime/   # SSE proxy for PocketBase
│       │   │   ├── mcp/        # MCP server endpoint
│       │   │   └── health/     # Health check
│       │   └── layout.tsx      # Root layout
│       ├── components/         # React components (shadcn/ui)
│       ├── hooks/              # Custom React hooks
│       ├── lib/                # Utilities and services
│       │   ├── mcp/            # MCP server and tools
│       │   ├── services/       # Business logic services
│       │   ├── stores/         # Zustand stores
│       │   ├── events/         # Event bus
│       │   ├── auth.ts         # Auth middleware
│       │   ├── pocketbase.ts   # PocketBase client
│       │   └── errors.ts       # Error handling
│       └── types/              # TypeScript type definitions
├── packages/
│   └── shared/                 # Shared package
│       └── src/
│           ├── schemas/        # Zod validation schemas
│           ├── types/          # TypeScript types
│           └── constants/      # Shared constants
├── pocketbase/
│   ├── pb_migrations/          # Database migrations
│   └── schema.ts               # TypeScript types for collections
├── worker/
│   └── index.ts                # Background job worker
├── e2e/                        # Playwright E2E tests
├── tests/                      # Unit and component tests
├── docker-compose.yml          # Docker Compose configuration
├── Dockerfile.web              # Web container build
├── Dockerfile.pocketbase       # PocketBase container build
├── Dockerfile.worker           # Worker container build
├── turbo.json                  # Turborepo configuration
└── package.json                # Root package.json

Available Scripts

Command	Description
npm run dev	Start all packages in development mode
npm run build	Build all packages for production
npm run lint	Run linting across all packages
npm run test	Run unit and component tests (Jest)
npm run test:e2e	Run Playwright E2E tests
npm run test:e2e:ui	Run Playwright tests with UI mode
npm run test:e2e:report	Show Playwright test report
npm run typecheck	Run TypeScript type checking
npm run db:generate	Generate database types

Environment Variables

Variable	Description	Default
POCKETBASE_URL	PocketBase server URL	http://localhost:8090
POCKETBASE_ADMIN_TOKEN	Admin authentication token	(required for worker)
NODE_ENV	Environment (development, production)	development

Create a .env.local file in the root directory for local development.

Testing

Unit and Component Tests

npm run test

Runs Jest tests across all packages. Tests are located in tests/ and alongside components.

E2E Tests

# Run all E2E tests
npm run test:e2e

# Run with UI mode (interactive)
npm run test:e2e:ui

# View test report
npm run test:e2e:report

Playwright tests are in e2e/ and cover:

• Authentication flows
• Task management
• Habit tracking
• Project organization
• Note editing
• Report generation
• Analytics dashboards
• Navigation and settings

Tests run against five browser configurations: Chromium, Firefox, WebKit, Mobile Chrome, and Mobile Safari.

Deployment

Docker Compose (Recommended)

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

# Rebuild after code changes
docker compose up -d --build

Environment Configuration

Set these in your deployment environment:

POCKETBASE_URL=http://db:8090
POCKETBASE_ADMIN_TOKEN=your_secure_admin_token

Volumes

• project-e-pb-data: PocketBase database files
• project-e-web-uploads: Uploaded files

Health Checks

All containers include health checks:

• Web: GET /api/health
• PocketBase: GET /api/health

Documentation

• API Documentation: REST API endpoints, authentication, error handling
• MCP Server Documentation: Model Context Protocol tools and usage
• Deployment Guide: Production deployment, SSL, backups, monitoring
• Development Guide: Contributing, code structure, testing strategy
• Architecture Documentation: System design, data flow, security

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm run test && npm run test:e2e)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow existing code style (TypeScript, functional components)
• Update documentation for API changes
• Keep commits atomic and well-described
• Use conventional commit messages

Code Review Process

• All PRs require at least one review
• CI must pass (lint, typecheck, tests)
• Keep PRs focused on a single concern
• Write clear PR descriptions explaining the "why"

License

This project is private and proprietary.

Support

For issues and questions:

• Open an issue on GitHub
• Check the documentation in docs/
• Review existing issues for similar problems