Nicholai
e6c1b7c4a0
replace site-header with inline sidebar trigger, reduce dashboard padding/gaps, and adjust schedule page layout to flex properly within the content area.
COMPASS
Construction Open Management Platform for Automated System Solutions
COMPASS is an open-source construction project management system built with Next.js, designed as a 1:1 drop-in replacement for BuilderTrend - without the bloat, recurring SaaS costs, or vendor lock-in.
The Problem
Creating a new project at a construction company currently means:
- Manually generating project codes across multiple systems
- Filling out the same information in 3-4 different spreadsheets
- Setting up 50+ CSI folders manually (30+ minutes of clicking)
- Hoping nothing was missed or mis-typed
The Solution
With COMPASS:
- 2-minute project creation - Single form, everything auto-generated
- Auto-provisioning - Project code, folders, permissions, initial budget
- Zero recurring costs - Self-hosted, open-source
- Full data ownership - Your data, your infrastructure
Features
- Automated Project Setup - Template-based creation with auto-generated numbering
- Construction Lifecycle Management - Status tracking from inquiry through completion
- Dual Interfaces - Separate dashboards for internal teams and clients
- Budget Tracking - CSI-based budget structure with version control
- Schedule Management - Gantt charts with dependencies and critical path
- Change Order Workflow - Major/minor change orders with approval routing
- Contact Logging - Manual and auto-detected client interactions
- Document Management - S3-compatible file storage with versioning
Tech Stack
| Layer | Technology |
|---|---|
| Framework | Next.js 15 (App Router) |
| Language | TypeScript 5.x |
| UI | React 19, shadcn/ui, Tailwind CSS 4 |
| Database | PostgreSQL with Prisma ORM |
| Auth | WorkOS (SSO, directory sync) |
| Storage | S3-compatible (AWS S3 / MinIO) |
| Jobs | BullMQ + Redis |
| Resend |
Getting Started
Prerequisites
- Node.js 20+
- pnpm 9+
- PostgreSQL 15+
- Redis (for background jobs)
Quick Start
# Clone the repository
git clone https://github.com/your-org/compass.git
cd compass
# Install dependencies
pnpm install
# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration
# Set up database
pnpm db:push
pnpm db:seed
# Start development server
pnpm dev
Open http://localhost:3000 to see the application.
Environment Setup
Create a .env.local file with the following variables:
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/compass"
# Auth (WorkOS)
WORKOS_API_KEY="sk_..."
WORKOS_CLIENT_ID="client_..."
WORKOS_REDIRECT_URI="http://localhost:3000/api/auth/callback"
# Storage (S3-compatible)
S3_ENDPOINT="http://localhost:9000"
S3_ACCESS_KEY_ID="minioadmin"
S3_SECRET_ACCESS_KEY="minioadmin"
S3_BUCKET="compass-files"
# Email (Resend)
RESEND_API_KEY="re_..."
# Redis
REDIS_URL="redis://localhost:6379"
Deployment
Docker (Self-hosted)
# Build and start all services
docker compose up -d
# Run database migrations
docker compose exec app pnpm db:migrate
The Docker setup includes:
- Next.js application
- PostgreSQL database
- MinIO (S3-compatible storage)
- Redis (caching and job queues)
Cloudflare Workers
COMPASS can be deployed to Cloudflare Workers for edge deployment:
# Build for Cloudflare
pnpm build:cf
# Deploy
pnpm deploy:cf
Uses Cloudflare D1, R2, and Queues for a fully serverless deployment.
Documentation
Contributing
We welcome contributions! Please see our Contributing Guide for details.
License
COMPASS is open-source software licensed under the AGPL-3.0 License.
Support
- Documentation: docs.compass-pm.dev
- Issues: GitHub Issues
- Discussions: GitHub Discussions
COMPASS - Breaking the monopolistic stranglehold of expensive SaaS platforms on the construction industry.