Platform Architecture Overview

The Shift Platform is a Bun/TypeScript monorepo that provides infrastructure tooling for AI coding agents. Each service is an independent git submodule with its own repository, mounted into the platform monorepo. A single Hono-based gateway aggregates all service APIs in-process, exposing them on port 3000.

High-Level Design

At its core, the platform follows three key architectural principles:

Monorepo with submodule isolation -- Services share patterns and core libraries but are developed, versioned, and deployed as part of a unified gateway.
In-process API aggregation -- The gateway imports each service's createApp() factory and mounts it directly. There is no inter-service HTTP proxying (with the exception of the optional Stage proxy).
Pluggable storage -- Every service defines a store interface. The backing implementation (Convex, file-based, or gateway-backed) is selected at runtime via the SHIFT_STORAGE environment variable.

Gateway Routing

All client traffic enters through the gateway on port 3000. The gateway mounts service APIs under versioned prefixes:

Client --> Gateway (:3000)
           |-- /healthz              (platform-core health)
           |-- /api/v1/catalog/*     (yellowpages)
           |-- /api/v1/passport/*    (passport)
           |-- /api/v1/pulse/*       (pulse)
           |-- /api/v1/ledger/*      (ledger)
           |-- /api/v1/palette/*     (palette)
           |-- /api/v1/communication/* (communication)
           |-- /api/v1/inference/*   (inference)
           |-- /api/v1/git/*         (git)
           |-- /api/v1/stage/*       (stage -- proxy or in-process)
           +-- /*                    (static web UI)

Services are conditionally mounted based on feature flags. If a service's feature flag is disabled, its routes are not registered and requests to its prefix return 404.

Service Topology

Service	Directory	Type	Dev Port (API)	Dev Port (Web)	Storage Dir
Gateway	`packages/gateway`	API gateway	3000 (prod)	--	--
Platform Core	`packages/core`	Shared library	--	--	--
Yellow Pages	`yellowpages/`	CLI + API + Web	4001	4101	`.yellowpages/`
Passport	`passport/`	CLI + API + Web	4002	4102	`.passport/`
Pulse	`pulse/`	CLI + API + Web	4003	4103	`.pulse/`
Ledger	`ledger/`	CLI + API + Web	4004	4104	`.ledger/`
Stage (CLI)	`stage-cli/`	CLI + API + Web	4005	4105	--
Stage (Next.js)	`stage/`	Web + API routes	3000 (standalone)	--	Convex-backed
Palette	`palette/`	CLI + API + Web	4006	4106	`.palette/`
Communication	`communication/`	CLI + API + Web	4007	4107	`.communication/`
Inference	`inference/`	CLI + API	4008	--	`.inference/`
Git	`git/`	CLI + API	4009	--	`.shift-git/`
Billing	`billing/`	CLI + API + Web	4010	4110	`.billing/`

Admin dashboard overview of all platform services

Apps catalog showing published Stage apps with metadata

Per-Service Package Structure

Each service submodule follows a four-package layout:

<service>/
  packages/
    shared/src/       # Types, store interfaces, store implementations
    api/src/          # Hono API (createApp() factory, routes)
    cli/src/          # Commander.js CLI (commands, main entry)
    web/src/          # React SPA (pages, components)

shared -- Defines the service's data types and the ServiceStore interface. Contains store implementations for each backend (file, convex, gateway).
api -- Exports a createApp() factory that returns a Hono app. The gateway imports this factory to mount the service in-process.
cli -- Commander.js CLI with commands that support the output triple: human-readable (default), --json, and --quiet.
web -- React SPA served as static files by the gateway. Each service's web UI is built into the gateway's public/ directory.

Shared Code: @shift/platform-core

The packages/core directory publishes @shift/platform-core, a shared library used by all services:

Export Path	Purpose
`@shift/platform-core/output`	Chalk-based output helpers (success, error, info, warn, table, barChart)
`@shift/platform-core/exit-codes`	Semantic exit codes (0 through 5)
`@shift/platform-core/api/response`	API response envelope (`ok()`, `err()`, `ApiResponse<T>`)
`@shift/platform-core/api/error-handler`	Hono error handler middleware + `HttpError`, `badRequest()`, `notFound()`, `conflict()`
`@shift/platform-core/api/health`	`healthRoute()` factory for `/healthz` endpoints
`@shift/platform-core/storage`	`Repository<T>`, `EventRepository<T>` interfaces + `getStorageBackend()`
`@shift/platform-core/convex-client`	Generalized Convex HTTP client (`convexQuery()`, `convexMutation()`)
`@shift/platform-core/features`	Feature flag definitions and `isFeatureEnabled()`

Git Submodule Workflow

Services are git submodules -- independent repositories mounted in the platform. This means each service has its own commit history, branches, and release cycle.

# Clone with submodules
git clone --recurse-submodules <repo-url>

# Update all submodules to latest
git submodule update --remote --merge

# Work in a submodule
cd yellowpages
git checkout -b feature/my-change
# ... make changes, commit, push ...
cd ..
git add yellowpages
git commit -m "Update yellowpages submodule"

When making changes to a submodule, you must commit and push within the submodule first, then update the submodule reference in the platform root.

High-Level Design​

Gateway Routing​

Service Topology​

Per-Service Package Structure​

Shared Code: @shift/platform-core​

Git Submodule Workflow​