Skip to content

docs(readme): rewrite to reflect current platform #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NicholaiVogel merged 2 commits into from
Feb 16, 2026
Merged

docs(readme): rewrite to reflect current platform #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c34d996
docs(readme): rewrite to reflect current platform
NicholaiVogel Feb 16, 2026
622f4a3
docs(agents): update with new modules and commands
NicholaiVogel Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 59 additions & 10 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Branching: `<username>/<feature>` off main
Conventional commits: `type(scope): subject`
PRs: squash-merged to main
Deployment: manual `bun deploy` or automatic through cloudflare/github integration
Last Updated: 2026/02/12
Last Updated: 2026/02/15
This file: AGENTS.md -> Symlinked to CLAUDE.md and GEMINI.md
---

Expand Down Expand Up @@ -86,13 +86,31 @@ bun run db:migrate:local # apply migrations locally
bun run db:migrate:prod # apply migrations to production D1
```

testing:
```bash
bun test # vitest run (unit + integration)
bun test:watch # vitest in watch mode
bun test:coverage # vitest with coverage
bun test:integration # integration tests only (__tests__/integration/)
bun test:e2e # playwright e2e (web)
bun test:e2e:ui # playwright with UI inspector
bun test:e2e:desktop # playwright e2e for Tauri desktop
```

mobile (capacitor):
```bash
bun cap:sync # sync web assets + plugins to native projects
bun cap:ios # open xcode project
bun cap:android # open android studio project
```

desktop (tauri):
```bash
bun tauri:dev # tauri dev server
bun tauri:build # production tauri build
bun tauri:preview # tauri dev without file watching
```

Style & Conventions
---

Expand All @@ -108,7 +126,6 @@ typescript discipline
---

these rules are enforced by convention, not tooling. see [docs/development/conventions.md](docs/development/conventions.md) for the reasoning behind each one.
> TODO: Add testing suite

- no `any` -- use `unknown` with narrowing
- no `as` -- fix the types instead of asserting
Expand All @@ -133,7 +150,10 @@ tech stack
| ai agent | AI SDK v6 + OpenRouter |
| integrations | NetSuite REST API, Google Drive API |
| mobile | Capacitor (iOS + Android webview) |
| desktop | Tauri 2.0 (Rust backend, webview frontend) |
| rich text | TipTap (mentions, links, placeholder) |
| themes | 10 presets + AI-generated custom themes (oklch) |
| testing | Vitest (unit/integration), Playwright (e2e, web + Tauri) |
| deployment | Cloudflare Workers via OpenNext |


Expand All @@ -146,8 +166,12 @@ each module contributes schema tables, server actions, components, and optionall
- **google drive**: domain-wide delegation via service account in `src/lib/google/`. two-layer permissions (compass RBAC + workspace). see [docs/modules/google-drive.md](docs/modules/google-drive.md).
- **scheduling**: gantt charts, critical path, baselines in `src/lib/schedule/`. see [docs/modules/scheduling.md](docs/modules/scheduling.md).
- **financials**: invoices, vendor bills, payments, credit memos. tied to netsuite sync. see [docs/modules/financials.md](docs/modules/financials.md).
- **conversations** (WIP): slack-like channels and messaging. text/voice/announcement channels, threading, reactions, attachments. schema in `src/db/schema-conversations.ts`.
- **conversations**: slack-like channels and messaging. text/voice/announcement channels, threading, reactions, attachments, @mentions. schema in `src/db/schema-conversations.ts`. components in `src/components/conversations/`.
- **voice**: discord-style voice controls with user bar, transcription via `/api/transcribe/`. components in `src/components/voice/`, state in `use-voice-state.ts`.
- **offline sync**: queue-based sync engine in `src/lib/sync/` with conflict resolution. API routes at `/api/sync/` (checkpoint, delta, mutate).
- **desktop**: Tauri 2.0 wrapper in `src-tauri/`. keyboard shortcuts in `src/lib/desktop/shortcuts.ts`, window management in `src/lib/desktop/window-manager.ts`. components in `src/components/desktop/`.
- **mobile**: capacitor webview wrapper. the web app must never break because of native code -- all capacitor imports are dynamic, gated behind `isNative()`. see [docs/modules/mobile.md](docs/modules/mobile.md) and [docs/architecture/native-mobile.md](docs/architecture/native-mobile.md).
- **mcp**: model context protocol integration. schema in `src/db/schema-mcp.ts`, key management via `src/app/actions/mcp-keys.ts`.
- **themes**: per-user oklch color system, 10 presets, AI-generated custom themes. see [docs/development/theming.md](docs/development/theming.md).
- **plugins/skills**: github-hosted SKILL.md files inject into agent system prompt. full plugins provide tools, components, actions. see [docs/development/plugins.md](docs/development/plugins.md).
- **claude code bridge**: local daemon that routes inference through your own Anthropic API key. WebSocket connection gives the agent filesystem + terminal access alongside Compass tools. API key auth with scoped permissions. see [docs/modules/claude-code.md](docs/modules/claude-code.md).
Expand All @@ -160,21 +184,27 @@ project structure
src/
├── app/
│ ├── (auth)/ # auth pages (login, signup, etc)
│ ├── api/ # api routes (agent, push, netsuite, auth)
│ ├── api/ # api routes (agent, bridge, google, netsuite, push, sync, transcribe)
│ ├── dashboard/ # protected dashboard routes
│ ├── actions/ # server actions (27 files, all mutations)
│ ├── actions/ # server actions (32 files, all mutations)
│ ├── globals.css # tailwind + theme variables
│ └── layout.tsx # root layout (ChatProvider lives here)
├── components/
│ ├── ui/ # shadcn/ui primitives
│ ├── ai/ # shadcn AI components (Conversation, Message, Tool)
│ ├── agent/ # ai chat (ChatView, ChatProvider, ChatPanelShell)
│ ├── native/ # capacitor mobile components
│ ├── netsuite/ # netsuite connection ui
│ ├── auth/ # authentication components
│ ├── conversations/ # channels, messaging, threads, mentions
│ ├── desktop/ # tauri desktop components
│ ├── files/ # google drive file browser
│ ├── financials/ # invoice/bill components
│ ├── google/ # google integration ui
│ ├── native/ # capacitor mobile components
│ ├── netsuite/ # netsuite connection ui
│ ├── people/ # user management
│ ├── schedule/ # gantt and scheduling
│ ├── conversations/ # channels and messaging (WIP)
│ └── people/ # user management
│ ├── settings/ # settings dialogs
│ └── voice/ # voice controls and user bar
├── db/
│ ├── schema.ts # core tables
│ ├── schema-netsuite.ts
Expand All @@ -186,22 +216,29 @@ src/
│ ├── schema-mcp.ts
│ ├── schema-conversations.ts
│ └── schema-google.ts
├── hooks/ # react hooks (chat, native, audio)
├── hooks/ # ~19 hooks (chat, native, audio, voice, desktop, files, realtime, etc.)
├── lib/
│ ├── agent/ # ai agent harness + plugins/
│ ├── conversations/ # conversation utilities
│ ├── desktop/ # tauri shortcuts + window manager
│ ├── github/ # github integration
│ ├── google/ # google drive integration
│ ├── mcp/ # model context protocol
│ ├── native/ # capacitor platform detection + photo queue
│ ├── netsuite/ # netsuite integration
│ ├── push/ # push notification sender
│ ├── schedule/ # scheduling computation
│ ├── sync/ # offline sync engine (queue, conflict resolution)
│ ├── theme/ # theme presets, apply, fonts
│ ├── auth.ts # workos integration
│ ├── permissions.ts # rbac checks
│ └── validations/ # zod schemas
└── types/ # global typescript types

src-tauri/ # tauri 2.0 rust project (desktop app)
docs/ # full documentation (start with docs/README.md)
drizzle/ # database migrations (auto-generated)
__tests__/ # vitest integration tests
ios/ # xcode project (capacitor)
android/ # android studio project (capacitor)
```
Expand Down Expand Up @@ -265,4 +302,16 @@ sharp edges that will cost you debugging time if you don't know about them upfro

see [docs/modules/netsuite.md](docs/modules/netsuite.md) for full context.

### tauri / desktop

- all tauri imports must be dynamic and gated behind platform checks (same pattern as capacitor)
- `src-tauri/` contains the Rust backend with Cargo.toml and tauri config
- playwright e2e for desktop uses `TAURI=true` env flag
- keyboard shortcuts registered in `src/lib/desktop/shortcuts.ts`

### conversations / tiptap

- @mentions use TipTap mention extension -- mention data stored as JSON in message content
- DOMPurify import: use `dompurify` (not `isomorphic-dompurify`) for edge compatibility


182 changes: 39 additions & 143 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,160 +1,56 @@
# COMPASS
# Compass

**Construction Open Management Platform for Automated System Solutions**
An AI-native workspace platform that handles auth, deployment,
and real-time collaboration -- so you can focus on building
what actually matters.

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.
## Build With Direction

## The Problem
- **AI agent built in** -- every workspace ships with an intelligent
assistant that understands your domain and takes action through
tools you define
- **Modular by design** -- scheduling, financials, file management,
messaging. drop in what you need, leave out what you don't
- **Deploy anywhere** -- self-host, ship to desktop and mobile,
or deploy to the edge with Cloudflare
- **Enterprise auth** -- SSO, directory sync, and role-based access
control out of the box

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
## Quick Start

## 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
```bash
git clone https://github.com/High-Performance-Structures/compass.git
cd compass
bun install
cp .env.example .env.local # add your keys
bun run db:generate
bun run db:migrate:local
bun dev
```

- **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
See [docs/](docs/README.md) for detailed setup, environment
variables, and deployment options.

## 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 |
| Framework | Next.js 15 (App Router), React 19 |
| Language | TypeScript 5.x (strict) |
| UI | shadcn/ui, Tailwind CSS v4 |
| Database | Cloudflare D1 (SQLite) via Drizzle ORM |
| Auth | WorkOS (SSO, directory sync) |
| Storage | S3-compatible (AWS S3 / MinIO) |
| Jobs | BullMQ + Redis |
| Email | Resend |

## Getting Started

### Prerequisites

- Node.js 20+
- pnpm 9+
- PostgreSQL 15+
- Redis (for background jobs)

### Quick Start

```bash
# 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](http://localhost:3000) to see the application.

### Environment Setup

Create a `.env.local` file with the following variables:

```bash
# 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)

```bash
# 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:

```bash
# Build for Cloudflare
pnpm build:cf

# Deploy
pnpm deploy:cf
```

Uses Cloudflare D1, R2, and Queues for a fully serverless deployment.

## Documentation

- [Product Requirements (PRD)](../compass-roadmap/docs/PRD-v003-2026-01-17.md)
- [Architecture](../compass-roadmap/docs/architecture.md)
- [API Documentation](./docs/api.md)

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
| AI | AI SDK v6 + OpenRouter |
| Mobile | Capacitor (iOS + Android) |
| Desktop | Tauri 2.0 |
| Deployment | Cloudflare Workers via OpenNext |

## License

COMPASS is open-source software licensed under the [AGPL-3.0 License](LICENSE).

## Support

- **Documentation**: [docs.compass-pm.dev](https://docs.compass-pm.dev)
- **Issues**: [GitHub Issues](https://github.com/your-org/compass/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/compass/discussions)
[AGPL-3.0](LICENSE)

---
## Links

**COMPASS** - Breaking the monopolistic stranglehold of expensive SaaS platforms on the construction industry.
- [Documentation](docs/README.md)
- [Issues](https://github.com/High-Performance-Structures/compass/issues)
- [Discussions](https://github.com/High-Performance-Structures/compass/discussions)
Loading