Nicholai
dc0cd40b13
Add local daemon that routes inference through user's own Anthropic API key with filesystem and terminal access. Includes WebSocket transport, MCP tool adapter, and API key auth. Key components: - compass-bridge package: local daemon with tool registry - WebSocket transport for agent communication - MCP API key management with HMAC auth and scoped permissions - Usage tracking (tool calls, duration, success/failure) - Settings UI for Claude Code configuration - Migration 0019: mcp_api_keys and mcp_usage tables - Test suite for auth and transport layers Co-authored-by: Nicholai <nicholaivogelfilms@gmail.com>
Compass Documentation
Compass is two things: a platform and a product.
Compass Core is an agentic dashboard platform -- authentication, an AI assistant, visual theming, a plugin system, and custom dashboards. It's built with Next.js 15, React 19, Cloudflare D1, and the AI SDK. It's generic. Any industry could use it.
HPS Compass is a construction project management product built on top of Compass Core. It adds scheduling with Gantt charts, financial tracking tied to NetSuite, Google Drive integration for project documents, and a Capacitor mobile app for field workers. It's specific to construction, but the architecture is designed so other industries could build their own module packages.
architecture
How the core platform works.
- overview -- the two-layer architecture, tech stack, project structure, how everything connects
- data layer -- Drizzle ORM on Cloudflare D1, schema conventions, migration workflow
- server actions -- the data mutation pattern, auth checks, error handling, revalidation
- auth system -- WorkOS integration, middleware, session management, RBAC
- AI agent -- OpenRouter provider, tool system, system prompt, unified chat architecture, usage tracking
modules
The construction-specific modules that make up HPS Compass.
- overview -- what the module system is, core vs module boundary, how modules integrate
- netsuite -- bidirectional ERP sync: OAuth, HTTP client, rate limiter, sync engine, mappers, gotchas
- google drive -- domain-wide delegation, JWT auth, drive client, two-layer permissions, file browser
- scheduling -- Gantt charts, critical path analysis, dependency management, baselines, workday exceptions
- financials -- invoices, vendor bills, payments, credit memos, NetSuite sync tie-in
- mobile -- Capacitor native app, offline photo queue, push notifications, biometric auth
- claude code -- local bridge daemon, own Anthropic API key, filesystem + terminal tools, WebSocket protocol
development
How to work on Compass.
- getting started -- local setup, environment variables, dev server, database, deployment
- conventions -- TypeScript discipline, component patterns, file organization
- theming -- oklch color system, preset themes, custom theme generation, how applyTheme works
- plugins -- skills system, plugin manifests, registry, building new plugins
quick reference
bun dev # dev server on :3000
bun run build # production build
bun deploy # build + deploy to cloudflare workers
bun run db:generate # generate migrations from schema
bun run db:migrate:local # apply migrations locally
bun run db:migrate:prod # apply migrations to production
bun lint # eslint
See getting started for full setup instructions.