jake/compassmock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* docs(readme): rewrite to reflect current platform

The README was referencing PostgreSQL, Prisma, pnpm, Redis,
BullMQ, and construction-specific features that no longer
reflect the actual stack or positioning. Rewritten to align
with the landing page messaging and current tech stack.

* docs(agents): update with new modules and commands

Add testing, desktop, and tauri commands. Expand module
listings with voice, offline sync, desktop, and MCP.
Update project structure tree and add tauri/tiptap gotchas.

---------

Co-authored-by: Nicholai <nicholaivogelfilms@gmail.com>
This commit is contained in:
Nicholai 2026-02-15 20:49:04 -07:00 committed by GitHub
parent 143e6b2c46
commit 49518d3633
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 98 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
AGENTS.md
View File

@ -5,7 +5,7 @@ Branching: `<username>/<feature>` off main
Conventional commits: `type(scope): subject` Conventional commits: `type(scope): subject`
PRs: squash-merged to main PRs: squash-merged to main
Deployment: manual `bun deploy` or automatic through cloudflare/github integration 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 This file: AGENTS.md -> Symlinked to CLAUDE.md and GEMINI.md
--- ---
@ -86,6 +86,17 @@ bun run db:migrate:local # apply migrations locally
bun run db:migrate:prod # apply migrations to production D1 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): mobile (capacitor):
```bash ```bash
bun cap:sync # sync web assets + plugins to native projects bun cap:sync # sync web assets + plugins to native projects
@ -93,6 +104,13 @@ bun cap:ios # open xcode project
bun cap:android # open android studio 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 Style & Conventions
--- ---
@ -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. 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 `any` -- use `unknown` with narrowing
- no `as` -- fix the types instead of asserting - no `as` -- fix the types instead of asserting
@ -133,7 +150,10 @@ tech stack
| ai agent | AI SDK v6 + OpenRouter | | ai agent | AI SDK v6 + OpenRouter |
| integrations | NetSuite REST API, Google Drive API | | integrations | NetSuite REST API, Google Drive API |
| mobile | Capacitor (iOS + Android webview) | | 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) | | themes | 10 presets + AI-generated custom themes (oklch) |
| testing | Vitest (unit/integration), Playwright (e2e, web + Tauri) |
| deployment | Cloudflare Workers via OpenNext | | deployment | Cloudflare Workers via OpenNext |
@ -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). - **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). - **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). - **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). - **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). - **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). - **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). - **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).
@ -160,21 +184,27 @@ project structure
src/ src/
├── app/ ├── app/
│ ├── (auth)/ # auth pages (login, signup, etc) │ ├── (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 │ ├── dashboard/ # protected dashboard routes
│ ├── actions/ # server actions (27 files, all mutations) │ ├── actions/ # server actions (32 files, all mutations)
│ ├── globals.css # tailwind + theme variables │ ├── globals.css # tailwind + theme variables
│ └── layout.tsx # root layout (ChatProvider lives here) │ └── layout.tsx # root layout (ChatProvider lives here)
├── components/ ├── components/
│ ├── ui/ # shadcn/ui primitives │ ├── ui/ # shadcn/ui primitives
│ ├── ai/ # shadcn AI components (Conversation, Message, Tool)
│ ├── agent/ # ai chat (ChatView, ChatProvider, ChatPanelShell) │ ├── agent/ # ai chat (ChatView, ChatProvider, ChatPanelShell)
│ ├── native/ # capacitor mobile components │ ├── auth/ # authentication components
│ ├── netsuite/ # netsuite connection ui │ ├── conversations/ # channels, messaging, threads, mentions
│ ├── desktop/ # tauri desktop components
│ ├── files/ # google drive file browser │ ├── files/ # google drive file browser
│ ├── financials/ # invoice/bill components │ ├── financials/ # invoice/bill components
│ ├── google/ # google integration ui
│ ├── native/ # capacitor mobile components
│ ├── netsuite/ # netsuite connection ui
│ ├── people/ # user management
│ ├── schedule/ # gantt and scheduling │ ├── schedule/ # gantt and scheduling
│ ├── conversations/ # channels and messaging (WIP) │ ├── settings/ # settings dialogs
│ └── people/ # user management │ └── voice/ # voice controls and user bar
├── db/ ├── db/
│ ├── schema.ts # core tables │ ├── schema.ts # core tables
│ ├── schema-netsuite.ts │ ├── schema-netsuite.ts
@ -186,22 +216,29 @@ src/
│ ├── schema-mcp.ts │ ├── schema-mcp.ts
│ ├── schema-conversations.ts │ ├── schema-conversations.ts
│ └── schema-google.ts │ └── schema-google.ts
├── hooks/ # react hooks (chat, native, audio) ├── hooks/ # ~19 hooks (chat, native, audio, voice, desktop, files, realtime, etc.)
├── lib/ ├── lib/
│ ├── agent/ # ai agent harness + plugins/ │ ├── agent/ # ai agent harness + plugins/
│ ├── conversations/ # conversation utilities
│ ├── desktop/ # tauri shortcuts + window manager
│ ├── github/ # github integration
│ ├── google/ # google drive integration │ ├── google/ # google drive integration
│ ├── mcp/ # model context protocol
│ ├── native/ # capacitor platform detection + photo queue │ ├── native/ # capacitor platform detection + photo queue
│ ├── netsuite/ # netsuite integration │ ├── netsuite/ # netsuite integration
│ ├── push/ # push notification sender │ ├── push/ # push notification sender
│ ├── schedule/ # scheduling computation │ ├── schedule/ # scheduling computation
│ ├── sync/ # offline sync engine (queue, conflict resolution)
│ ├── theme/ # theme presets, apply, fonts │ ├── theme/ # theme presets, apply, fonts
│ ├── auth.ts # workos integration │ ├── auth.ts # workos integration
│ ├── permissions.ts # rbac checks │ ├── permissions.ts # rbac checks
│ └── validations/ # zod schemas │ └── validations/ # zod schemas
└── types/ # global typescript types └── types/ # global typescript types
src-tauri/ # tauri 2.0 rust project (desktop app)
docs/ # full documentation (start with docs/README.md) docs/ # full documentation (start with docs/README.md)
drizzle/ # database migrations (auto-generated) drizzle/ # database migrations (auto-generated)
__tests__/ # vitest integration tests
ios/ # xcode project (capacitor) ios/ # xcode project (capacitor)
android/ # android studio project (capacitor) android/ # android studio project (capacitor)
``` ```
@ -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. 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
README.md
View File

@ -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: ## Quick Start
- 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 ```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
```
With COMPASS: See [docs/](docs/README.md) for detailed setup, environment
- **2-minute project creation** - Single form, everything auto-generated variables, and deployment options.
- **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 ## Tech Stack
| Layer | Technology | | Layer | Technology |
|-------|------------| |-------|------------|
| Framework | Next.js 15 (App Router) | | Framework | Next.js 15 (App Router), React 19 |
| Language | TypeScript 5.x | | Language | TypeScript 5.x (strict) |
| UI | React 19, shadcn/ui, Tailwind CSS 4 | | UI | shadcn/ui, Tailwind CSS v4 |
| Database | PostgreSQL with Prisma ORM | | Database | Cloudflare D1 (SQLite) via Drizzle ORM |
| Auth | WorkOS (SSO, directory sync) | | Auth | WorkOS (SSO, directory sync) |
| Storage | S3-compatible (AWS S3 / MinIO) | | AI | AI SDK v6 + OpenRouter |
| Jobs | BullMQ + Redis | | Mobile | Capacitor (iOS + Android) |
| Email | Resend | | Desktop | Tauri 2.0 |
| Deployment | Cloudflare Workers via OpenNext |
## 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.
## License ## License
COMPASS is open-source software licensed under the [AGPL-3.0 License](LICENSE). [AGPL-3.0](LICENSE)
## Support ## Links
- **Documentation**: [docs.compass-pm.dev](https://docs.compass-pm.dev) - [Documentation](docs/README.md)
- **Issues**: [GitHub Issues](https://github.com/your-org/compass/issues) - [Issues](https://github.com/High-Performance-Structures/compass/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/compass/discussions) - [Discussions](https://github.com/High-Performance-Structures/compass/discussions)
---
**COMPASS** - Breaking the monopolistic stranglehold of expensive SaaS platforms on the construction industry.