Docs
getting-startedOverview

Getting started

Five different “what are you building?” paths. Pick the one that fits and follow it through.

Pick your path

You’re buildingRead this
A third-party app that integrates with Loop via OAuthBuild a partner app
A first-party Loop app (my-loop-health, admin, loopbio)Build a Loop app
A new platform service inside this repoBuild a platform service
A scheduled background job (cron, batch processor)Build a background job
You want the complete checklist for shipping anythingFull checklist

Prerequisites (all paths)

  • Node.js 22.x or newer
  • pnpm 9.x (npm install -g pnpm)
  • Doppler CLI (for env/secrets management)
  • AWS CLI configured (you’ll need read access to dev secrets at minimum)
  • gh CLI (brew install gh) — for PR workflows
  • A GitHub identity with access to the TheLoopWay org

Repository layout you’ll see

loop-platform/
├── apps/
│   ├── docs/                  ← you are here
│   ├── developer-portal/      ← register OAuth apps
│   └── sdk-canary/            ← SDK install + typing canary
├── packages/
│   ├── contracts/             ← event schemas, EVENT_NAMES, OAUTH_ERRORS, WEBHOOK_HEADERS
│   ├── core/                  ← Result<T>, errors, logger, locks
│   ├── hono/                  ← service framework, middleware
│   ├── scopes/                ← OAuth scope taxonomy
│   ├── brands/                ← brand catalog
│   ├── hosts/                 ← hostname helpers
│   ├── sdk/                   ← LoopClient (OAuth), M2MClient
│   └── sdk-<service>/         ← typed clients (one per service)
├── services/
│   ├── _template/             ← canonical service shape
│   └── <service>/             ← 23 services
└── docs/
    ├── decisions/             ← ADRs (historical)
    ├── runbooks/              ← operational
    └── architecture/          ← gap specs, audits

Every service follows the same shape (per ADR-0037). When in doubt, copy from services/_template/.

What you need to know before reading any further

Three concepts that show up everywhere:

  1. System overview — one diagram, the whole platform.
  2. Auth model — OAuth + M2M + Clerk + WorkOS.
  3. Events — dual-bus pattern, outbox, at-least-once.

Read them once. Reference them often.

Related

Vendor graphBuild a partner app