Skip to main content

Contributing to The Shift Platform

Welcome, and thank you for your interest in contributing to The Shift Platform. This section covers everything you need to get started -- from setting up your development environment to submitting pull requests.

Two Development Modes​

Simple Mode​

The fastest way to develop locally. Starts all service APIs, web UIs, and the gateway in a single command:

bun install
bun run dev

This launches all services on their individual dev ports (4001-4010 for APIs, 4101-4110 for web UIs) and the gateway on port 3000.

Production-Like Mode​

Run the full stack in a local Kubernetes cluster using kind. This mirrors the production deployment topology:

make dev-k8s
make dev-k8s-status
curl http://shift.lvh.me/healthz

See the Local K8s guide for details.

Before Submitting​

Before opening a pull request, ensure:

  1. Lint passes -- bun run check (Biome format + lint)
  2. Tests pass -- bun run test (bun:test across all services)
  3. Types check -- TypeScript strict mode with no errors
bun run check
bun run test
  • Development Setup -- Prerequisites, cloning, installing, and running
  • Conventions -- Coding standards for TypeScript, formatting, testing, CLI, and API design
  • PR Workflow -- Where to open PRs and how to handle submodule changes