Onboarding

A structured path for new engineers joining the Loop Platform. Follow these milestones to ramp up progressively — from local setup through your first production-ready feature PR.

Day 1

Get the repo running locally and absorb the foundational conventions.

Clone and run

git clone git@github.com:AlteredAdmin/loop-platform.git
cd loop-platform
pnpm install
pnpm dev

Read the conventions

Open CLAUDE.md at the repo root. This is the single source of truth for code style, commit format, deploy stages, and what you must never do.

Then read the overlay for your assigned service at services/<your-service>/CLAUDE.md. It contains service-specific gotchas that override or extend the root file.

Verify your setup

Run the full check suite to confirm everything compiles and passes:

pnpm typecheck && pnpm test && pnpm lint

Browse the docs

Start the docs site and explore:

pnpm --filter docs dev

Open http://localhost:3200 in your browser. Familiarize yourself with the Build guides and Concepts pages.

Read foundational ADRs

Week 1

Make your first contribution and understand the CI pipeline.

First PR: improve a service README

Pick any service under services/. Add a Local development section to its README.md showing how to run just that service:

pnpm --filter <service-name> dev

This is a low-risk way to learn the PR workflow — branch naming, conventional commits, changesets, and CI checks.

Understand convention enforcement

Read ADR-0036 to understand what CI checks enforce: service.yaml validation, OpenAPI drift detection, changeset presence, audit log wiring, and more.

Deploy to dev

Deploy your service to the shared dev stage to see SST in action:

pnpm sst deploy --stage dev

Explore your service contract

Read the service.yaml at the root of your assigned service. It declares the service’s dependencies, events, SLA, and owner. CI validates it against @platform/contracts/service-yaml.schema.json.

Create a changeset

Practice the changeset workflow with a small documentation fix:

pnpm changeset

Pick the affected package, select patch, and write a one-line summary of the user-visible change.

Review event contracts

Browse packages/contracts/src/events/ to see how events are declared and registered. Every event published by a service must have a matching schema here.

Month 1

Ship a real feature and prepare for on-call responsibilities.

First feature PR

Implement a new endpoint on your assigned service. Follow the pattern in services/_template/:

1. Add the route using @hono/zod-openapi with request/response schemas.
2. Wire audit logging via auditMiddleware.
3. Enforce OAuth scopes with requireScope.
4. Regenerate OpenAPI: pnpm openapi:gen.
5. Write tests covering success, validation errors, and auth failures.

See the Style Guide for documentation standards when writing your endpoint docs.

Write a migration

Use Drizzle Kit to generate and apply a schema migration:

pnpm drizzle-kit generate
pnpm drizzle-kit migrate

Migrations live in services/<name>/migrations/. Commit the generated SQL files.

Publish an event

Use @platform/events to publish your first domain event:

import { publishEvent } from "@platform/events";
 
await publishEvent("order.created", {
  orderId: "ord_abc123",
  userId: "usr_xyz789",
  amount: 4999,
});

The event schema must exist in packages/contracts/src/events/ and be registered in registry.ts.

Add convention tests

Run the convention checker against your service and fix any violations:

pnpm check:conventions

Review the production-readiness checklist

Before your service can be promoted to status: ga, it must satisfy every item on the Production-Readiness Checklist. Review it now so you know what “done” looks like.

Shadow on-call

Join the on-call rotation as a shadow. Read docs/runbooks/oncall-rotation.md and your service’s RUNBOOK.md to understand escalation paths and common failure modes.

Next Steps

• Production-Readiness Checklist — The full checklist your service must satisfy.
• Style Guide — Writing and documentation standards.
• Service Architecture — How services are structured and communicate.
• Install an SDK — Set up the SDK for local development.