docs(sidebar): add comprehensive sidebar component documentation (#72 )

- Add docs/development/sidebar.md with full architecture explanation
- Cover desktop expanded/collapsed states and mobile sheet rendering
- Document the gap-and-container pattern for layout stability
- Explain collapsed state centering, mobile-specific sizing
- Document the flicker bug fix in useIsMobile hook
- Add animation performance notes (will-change, ease-out)
- Include component reference and common patterns
- Update AGENTS.md with conversations module (WIP) and schema count
- Add sidebar.md to docs/README.md development section

Co-authored-by: Nicholai <nicholaivogelfilms@gmail.com>

2026-02-12 15:26:34 -07:00

3.3 KiB

Executable File

Raw Blame History

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
sidebar -- sidebar component architecture, desktop vs mobile, collapsed state, animations
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.

3.3 KiB Executable File Raw Blame History