Skip to main content
This guide covers setting up a local development environment for the ORbit web application.

​
Prerequisites

  • Node.js 18+ and npm
  • Git for version control
  • Supabase CLI for database management
  • A code editor (VS Code recommended)

​
Clone and install

1

Clone the repository

git clone <repository-url>
cd orbit/apps/web/or-flow-app
2

Install dependencies

npm install
You should see no errors in the install output.

​
Environment variables

Create a .env.local file in apps/web/or-flow-app/ with your Supabase credentials: 
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
Never commit .env.local or any file containing secrets to version control.

​
Run the development server

npm run dev
The app will be available at http://localhost:3000.

​
Database setup

ORbit uses Supabase (PostgreSQL). To work with the database: 
supabase link --project-ref your-project-ref

​
Apply migrations

supabase db push --workdir /path/to/orbit/apps/web/or-flow-app

​
Create a new migration

supabase migration new migration_name --workdir /path/to/orbit/apps/web/or-flow-app
Migration files are stored in supabase/migrations/ and are shared by both the web and iOS applications.

​
Project structure

apps/web/or-flow-app/
├── app/                    # Next.js App Router pages (~60 routes)
├── components/             # React components (~329 files)
│   ├── ui/                 # shadcn base components
│   ├── layouts/            # DashboardLayout, Sidebar, Header
│   ├── cases/              # Case management (38 files)
│   ├── dashboard/          # Dashboard (24 files)
│   ├── analytics/          # Analytics pages
│   ├── data-quality/       # Data quality (13 files)
│   ├── settings/           # Settings pages
│   └── block-schedule/     # Block scheduling
├── lib/
│   ├── dal/                # Data access layer (core, cases, facilities, users, lookups)
│   ├── hooks/              # React hooks (21 files)
│   ├── constants/          # Metrics catalog, status config
│   └── utils/              # Formatting, analytics utilities
├── types/                  # TypeScript type definitions
├── supabase/migrations/    # Database migrations (68 files)
└── docs/                   # Internal documentation

​
Development workflow

ORbit uses a structured development workflow built around Claude Code:

​
Feature development

1

Write a feature spec

Create docs/active-feature.md describing what you want to build.
2

Run /audit

Scans the codebase, interviews you about requirements, and creates a phased implementation plan in docs/implementation-plan.md.
3

Run /phase-start

Implements one phase, runs the 3-stage test gate, commits, and stops. Each phase is one atomic commit.
4

Repeat for each phase

Start a new session and run /phase-start for the next phase. Continue until all phases are complete.
5

Merge to main

Once all phases pass, merge the feature branch to main.

​
Commands

CommandPurpose
/auditAnalyze feature spec and create implementation plan
/phase-startExecute the next pending phase
/wrap-upCommit work, log session state
/fixQuick targeted fix without planning overhead
/migrateCreate a database migration

​
Testing

ORbit uses a 3-stage testing gate after every phase:
  1. Unit tests — does the new code work in isolation?
  2. Integration tests — does it work with what consumes it?
  3. Workflow tests — end-to-end scenario covering user actions before and after
npm run test           # Run test suite
npm run typecheck      # TypeScript type checking
npm run lint           # ESLint

​
Git conventions

  • Feature branches: feature/descriptive-name
  • One commit per phase: feat(scope): phase N - description
  • Undo a phase: git revert HEAD
  • Merge to main only when all phases are verified

​
Key rules

These rules are enforced across the codebase. Violating them causes bugs.
  • Always use useSupabaseQuery for data fetching — never raw Supabase client calls in components
  • Always filter by facility_id — RLS enforces this
  • Always use facility_milestone_id — never milestone_type_id in case_milestones
  • Always filter is_active = true — 20+ tables use soft deletes
  • No any types — TypeScript strict mode
  • Use the logger — structured JSON logging, not console.log
The git repo lives inside apps/web/or-flow-app/, not at the monorepo root. Always run git commands from within that directory.

​
Next steps

Architecture

Deep dive into the database and system architecture.

Milestone system

Understand the template-based milestone architecture.