Paintjob - Automated Painting System

A comprehensive full-stack application for planning and automating wall painting projects with motion path generation.

---

📖 Overview

Paintjob is a production-ready system that combines:

• Backend API (FastAPI + PostgreSQL) for managing users, projects, rooms, walls, and generating motion paths
• Frontend Editor (Next.js 15) for visual planning with canvas-based wall and window editing

This repository contains both the backend (paintjob/) and frontend (paintjob-fe/) applications in a monorepo structure.

🎥 Video Demonstration

Watch a quick overview of the Paintjob system:

🎬 Watch on YouTube

---

🚨 Important Legal Notice

This repository is VIEW-ONLY for external contributors.

• You DO NOT own any code in this repository
• All contributions become property of the repository owner
• By contributing, you agree to the Contributor License Agreement (CLA)
• You MUST read and accept the CLA before contributing

See CONTRIBUTING.md for strict contribution guidelines.

---

📚 Documentation

Core Documentation

• API Documentation - Complete API reference with endpoints, schemas, and examples
• Testing Guide - Comprehensive guide for running and writing tests
• Frontend README - Frontend editor features and usage guide
• Contributor License Agreement - Legal agreement for contributors
• Contributing Guidelines - Strict rules for contributions

Quick Links

• Backend Setup | Frontend Setup
• Running the Application
• Project Structure
• Environment Variables

---

🚀 Quick Start

Prerequisites

Required:

• Python 3.11+
• Node.js 18+ and pnpm
• PostgreSQL

Verify installations:

python3 --version    # Should be 3.11+
pnpm --version       # Should be 8.0+
      

---

🔧 Backend Setup (paintjob/)

The backend is a FastAPI application with PostgreSQL database.

1. Navigate to Backend Directory

cd paintjob

2. Create Python Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# On macOS/Linux:
source venv/bin/activate

3. Install Poetry and Dependencies

# Install poetry if not already installed
pip install poetry

# Install all dependencies using poetry
poetry install

4. Configure Environment Variables

Important: Environment files are already provided in the repository.

Check that .env file exists in the paintjob/ directory with these variables:

Note: Update DATABASE_URL with your actual PostgreSQL credentials.

5. Run Database Migrations

# Apply all migrations to create tables
alembic upgrade head

6. Start the Backend Server

# Run the FastAPI application
python3 main.py

The API will be available at http://localhost:8000

API Endpoints:

• Interactive docs: http://localhost:8000/docs
• Alternative docs: http://localhost:8000/redoc
• API base: http://localhost:8000/api

---

🎨 Frontend Setup (paintjob-fe/)

The frontend is a Next.js 15 application with TypeScript and React.

1. Navigate to Frontend Directory

cd paintjob-fe

2. Install Dependencies with pnpm

# Install all dependencies
pnpm install

3. Configure Environment Variables

Important: Environment files are already provided in the repository.

Check that .env.local file exists in the paintjob-fe/ directory:

NEXT_PUBLIC_API_URL=http://localhost:8000/api

4. Start the Development Server

# Run Next.js development server
pnpm dev

The frontend will be available at http://localhost:3000

---

▶️ Running the Application

Start Backend

cd paintjob
source venv/bin/activate  # or .\venv\Scripts\Activate.ps1 on Windows
python3 main.py

Start Frontend (in a new terminal)

cd paintjob-fe
pnpm dev

Access the Application

1. Open browser to http://localhost:3000
2. Create an account or login
3. Click "Open Editor" to start creating projects

---

🧪 Running Tests

Backend Tests

cd paintjob

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/api/test_project_flow.py -v

# Run with coverage
pytest --cov=api --cov-report=html

See TESTING_GUIDE.md for comprehensive testing documentation.

Frontend Tests

cd paintjob-fe
# Tests to be added
pnpm test

---

📁 Project Structure

paintjob/                         # Root monorepo
├── README.md                     # This file
├── CLA.md                        # Contributor License Agreement
├── CONTRIBUTING.md               # Contribution guidelines
├── TESTING_GUIDE.md             # Testing documentation
│
├── paintjob/                     # Backend FastAPI application
│   ├── main.py                   # Application entry point
│   ├── pyproject.toml            # Poetry dependencies
│   ├── alembic.ini              # Database migration config
│   ├── API_DOCUMENTATION.md     # Complete API reference
│   ├── alembic/                 # Database migrations
│   │   └── versions/            # Migration files
│   ├── api/                     # Application code
│   │   ├── auth.py              # JWT authentication
│   │   ├── database.py          # Database configuration
│   │   ├── models/              # SQLAlchemy models
│   │   ├── repos/               # Repository pattern
│   │   ├── routers/             # API endpoints
│   │   ├── schemas/             # Pydantic schemas
│   │   ├── services/            # Business logic
│   │   └── utils/               # Utilities
│   └── tests/                   # Test suite
│       ├── api/                 # API integration tests
│       └── conftest.py          # Test fixtures
│
└── paintjob-fe/                 # Frontend Next.js application
    ├── README.md                # Frontend documentation
    ├── package.json             # Node dependencies
    ├── next.config.ts           # Next.js configuration
    ├── src/
    │   ├── app/                 # Next.js App Router
    │   │   ├── page.tsx         # Home page
    │   │   └── editor/          # Editor page
    │   ├── components/          # React components
    │   │   ├── canvas/          # Konva canvas components
    │   │   ├── panels/          # Side panels
    │   │   ├── toolbar/         # Top toolbar
    │   │   └── ui/              # shadcn/ui components
    │   ├── hooks/               # Custom React hooks
    │   ├── lib/                 # Utilities and state
    │   │   ├── geometry/        # Geometric calculations
    │   │   ├── schema/          # Zod schemas
    │   │   └── state/           # Zustand store
    │   ├── models/              # TypeScript types
    │   └── services/            # API client services
    └── public/                  # Static assets

---

🔑 Environment Variables

Backend (paintjob/.env)

# Database
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/paintjob

# JWT Authentication
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=720

# Optional: For production
CORS_ORIGINS=http://localhost:3000

Frontend (paintjob-fe/.env.local)

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000/api

# Optional: For production
NEXT_PUBLIC_ENV=development

Note: These environment files are already included in the repository. Update values as needed for your setup.

---

🏗️ Tech Stack

Backend

• FastAPI - Modern async web framework
• SQLAlchemy - ORM with async support
• PostgreSQL - Relational database
• Alembic - Database migrations
• Pydantic - Data validation
• JWT - Token-based authentication
• Poetry - Dependency management
• Pytest - Testing framework

Frontend

• Next.js 15 - React framework (App Router)
• TypeScript - Type safety
• React Konva - Canvas rendering
• Zustand - State management
• Zod - Schema validation
• shadcn/ui - UI components (Radix UI)
• Tailwind CSS - Styling
• pnpm - Package manager

---

🌟 Key Features

Backend API

• ✅ User authentication with JWT tokens
• ✅ Project and room management
• ✅ Wall geometry and obstacle tracking
• ✅ Motion path generation for automated painting
• ✅ RESTful API with comprehensive validation
• ✅ Cascade deletion for hierarchical data
• ✅ Full test coverage

Frontend Editor

• ✅ Canvas-based visual editor (Konva.js)
• ✅ Drag-and-drop interface
• ✅ Project/room/wall hierarchy
• ✅ Real-time dimension editing with sliders
• ✅ Window and door placement
• ✅ Grid and snap functionality
• ✅ Undo/redo history
• ✅ Import/export JSON scenes
• ✅ Zoom and pan controls

---

📄 API Endpoints Overview

See API_DOCUMENTATION.md for complete reference.

Authentication

• POST /api/users/ - Create user account
• POST /api/users/login - Login and get JWT token
• GET /api/users/me - Get current user profile

Projects

• POST /api/projects/ - Create project
• GET /api/projects/ - List user's projects
• GET /api/projects/{id}/with-rooms - Get project with rooms
• PUT /api/projects/{id} - Update project
• DELETE /api/projects/{id} - Delete project (cascades)

Rooms & Walls

• POST /api/rooms/ - Create room
• POST /api/walls/ - Create wall
• GET /api/rooms/{id}/walls - Get walls for room
• PUT /api/walls/{id} - Update wall geometry

Motion Paths

• POST /api/paths/generate-motion-path - Generate painting path
• POST /api/paths/preview-path - Preview path statistics

---

🛠️ Development Commands

Backend

cd paintjob

# Install dependencies
poetry install

# Run development server
python3 main.py

# Run tests
pytest -v

# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1

Frontend

cd paintjob-fe

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build

# Run production build
pnpm start

# Lint code
pnpm lint

---

🐛 Troubleshooting

Backend Issues

Database connection fails:

# Check PostgreSQL is running
psql -U postgres -c "SELECT 1;"

# Verify DATABASE_URL in .env
cat paintjob/.env | grep DATABASE_URL

Poetry installation issues:

# Clear poetry cache
poetry cache clear --all pypi

# Reinstall dependencies
rm poetry.lock
poetry install

Migration errors:

# Reset database (⚠️ destroys all data)
alembic downgrade base
alembic upgrade head

Frontend Issues

Port 3000 already in use:

# Run on different port
pnpm dev -- -p 3001

pnpm not found:

# Install pnpm globally
npm install -g pnpm

Module not found errors:

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

---

📞 Support

For issues or questions:

1. Check the documentation in /docs
2. Review API_DOCUMENTATION.md
3. Check TESTING_GUIDE.md
4. Contact the repository owner

---

⚖️ License

Proprietary - All Rights Reserved

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

By accessing this repository:

• You agree to the terms in CLA.md
• You understand this is VIEW-ONLY access
• You acknowledge all contributions become property of the owner
• You agree to follow CONTRIBUTING.md guidelines

---

🤝 Contributing

READ THIS BEFORE CONTRIBUTING:

This repository has STRICT contribution rules:

1. Read and accept CLA.md first
2. Follow CONTRIBUTING.md guidelines
3. All contributions are VIEW-ONLY
4. You do NOT own any code you contribute

Summary:

• Fork and create pull requests only
• No direct commits to main
• All PRs require review and approval
• Contributors grant full rights to repository owner

See CONTRIBUTING.md for complete guidelines.

---

🎯 Roadmap

• Add frontend tests (Jest + React Testing Library)
• Implement motion path visualization
• Add real-time collaboration
• Mobile app (React Native)
• Docker containerization
• CI/CD pipeline
• Production deployment guides

---

📝 Changelog

See git commit history for detailed changes.

Version 1.0.0 (October 2025)

• Initial release
• Complete backend API
• Frontend editor
• Database migrations
• Comprehensive test suite

---

Made with ❤️ by the Paintjob Team

Last Updated: October 5, 2025