Project Management MVP - Complete Setup

Quick Start

1. Clone/Setup:

   cd pm
   cp .env.example .env

2. Start Services:

   # macOS/Linux
   ./scripts/start-mac.sh
   
   # Windows
   scripts\start-windows.bat

3. Access:

   • Backend: http://localhost:8000
   • Frontend: http://localhost:3000 (Part 3+)

Project Status

✅ Part 1: Planning

• Detailed plan created (docs/DETAILED_PLAN.md)
• Frontend architecture documented (frontend/AGENTS.md)
• Backend architecture documented (backend/AGENTS.md)

✅ Part 2: Docker Scaffolding & Basic Backend

• Docker Compose setup complete
• FastAPI backend initialized
• Start/Stop scripts for Mac, Windows, Linux
• Basic "Hello World" endpoints working
• Static HTML example page
• Environment configuration setup
• See docs/PART2_SETUP.md for detailed setup guide

✅ Part 3: Frontend Integration & Static Export

• Next.js frontend builds as a static export
• Backend serves the Kanban board at http://localhost:8000
• Frontend unit and Playwright tests pass

✅ Part 4: User Authentication

• Client-side login with the MVP credentials user / password
• Session persists in localStorage
• Kanban board is protected until sign-in
• Sign-out clears the session

✅ Part 6: Backend API Routes

• SQLite database is created and seeded on backend startup
• JWT authentication and user-scoped board/card APIs are available
• CRUD and card movement endpoints are covered by backend tests
• Backend API tests pass with 87% coverage

✅ Part 7: Frontend & Backend Integration

• Frontend login stores and sends the backend JWT
• Board data loads from SQLite through the FastAPI API
• Card creation, deletion, movement, and column renaming persist
• Loading, retry, rollback, and expired-session handling are covered
• All 5 API-backed Playwright tests pass

✅ Part 5: Database Schema Design

• SQLite schema documented and approved
• Schema includes users, boards, columns, cards, relationships, constraints, and indexes

⏳ Part 7-10: Coming Next

• Part 5: Database Schema Design
• Part 6: Backend API Routes
• Part 7: Frontend & Backend Integration
• Part 8: AI Connectivity Test
• Part 9: AI with Structured Outputs
• Part 10: AI Chat Sidebar UI

Key Files

File	Purpose
docker-compose.yml	Orchestrates all services
backend/app/main.py	FastAPI application
backend/pyproject.toml	Backend dependencies
.env.example	Environment variables template
scripts/start-*.sh/.bat	Start/stop automation
docs/DETAILED_PLAN.md	Complete project plan with checklists

Tech Stack

• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
• Backend: FastAPI, Python 3.12, SQLAlchemy
• Database: SQLite (local development)
• AI: OpenRouter (deepseek/deepseek-v4-flash-0731)
• Deployment: Docker Compose

Development Workflow

# Start everything
./scripts/start-mac.sh

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

# Stop everything
./scripts/stop-mac.sh

Testing

# Backend unit tests (Part 6+)
cd backend && uv run pytest

# Frontend unit tests
cd frontend && npm run test:unit

# Frontend E2E tests
cd frontend && npm run test:e2e

# All tests
npm run test:all

Documentation

• Setup Guide: docs/PART2_SETUP.md - Detailed Part 2 setup
• Project Plan: docs/DETAILED_PLAN.md - All 10 parts with checklists
• Frontend: frontend/AGENTS.md - Frontend architecture
• Backend: backend/AGENTS.md - Backend architecture

Environment Variables

See .env.example for all available options:

• OPENROUTER_API_KEY - Required for AI features (Part 8+)
• DATABASE_PATH - SQLite database location
• JWT_SECRET - Token signing secret
• BACKEND_PORT - Backend port (default 8000)

Troubleshooting

Services won't start

1. Check Docker is running: docker ps
2. Check ports aren't in use: lsof -i :8000 (macOS/Linux)
3. Check .env exists: cat .env
4. View logs: docker-compose logs

Can't connect to localhost:8000

1. Wait 5-10 seconds for backend to fully start
2. Check health: curl http://localhost:8000/api/health
3. Check Docker is running containers: docker ps

Docker image download fails

1. Verify internet connection
2. Check Docker daemon is connected: docker info
3. Try again - may be temporary network issue

Next Steps

See docs/DETAILED_PLAN.md Part 3 for integrating the frontend and serving the Kanban board.

---

For complete project details, see the AGENTS.md file or project documentation.