Platform team - onboarding & runbook index

This page is the team's home base. New joiners start at the top and work down; on-call engineers jump straight to the runbook index. If a section feels out of date, fix it in place and mention it in the next standup - this is living documentation, not an archive.

Onboarding

We aim to get a new engineer their first merged change in week one. The path below is intentionally small; depth comes later.

Before your first day

The IT team provisions most things ahead of time, but a few items need your input.

• a GitHub account added to the platform org (ask your buddy to confirm)
• VPN access - request via the internal portal, allow one business day
• a calendar hold for the daily standup at 09:30

Week one checklist

Work through these roughly in order. Tick them off as you go.

• [X] Clone the monorepo and run the local stack end to end
• [X] Pair with your buddy on a "good first issue"
• [ ] Get your first pull request reviewed and merged
• [ ] Shadow one on-call handover (read-only)
• [ ] Add yourself to the team directory

Don't try to understand the whole system in week one. Understand one slice deeply, and trust your colleagues for the rest. The map fills in faster than you'd expect.

Local environment

The bootstrap script handles dependencies, but the order matters on a fresh machine.

1. Install the toolchain pinned in .tool-versions
2. Run make bootstrap to fetch secrets and seed the database
3. Start the stack with make dev
4. Confirm the health endpoint returns green before opening a PR

If make bootstrap fails on the secrets step, you are almost certainly missing VPN access - see Before your first day.

Runbook index

Each service has a one-page runbook. The table below is the quick lookup; the subsections expand the two that page most often.

api-gateway

The gateway terminates TLS and fans requests out to internal services. Most incidents here are upstream, not the gateway itself.

Symptoms

• elevated 5xx with healthy upstreams usually means connection-pool exhaustion
• elevated latency with healthy 5xx usually means a slow downstream dependency

First response

• check the saturation dashboard before touching config
• if pool exhaustion is confirmed, scale out rather than raising pool limits[^pool]
• page the upstream owner from the table above if the cause is downstream

auth-service

Auth is tier 0: treat every incident as customer-facing until proven otherwise.

Token rotation

We rotate signing keys on a fixed cadence. ~~Keys were rotated manually during a maintenance window~~ → rotation is now fully automated and overlaps old and new keys for a grace period, so there is no longer a hard cutover. If you see a spike of invalid_signature errors, confirm the grace window has not lapsed before assuming a breach.

Decision log

We record meaningful technical decisions here so the reasoning survives the people who made it. Newest first.

2026-05 - Adopt structured logging everywhere

After a painful incident where free-text logs could not be correlated across services, we standardised on structured JSON logs with a shared trace ID.

• every service emits a trace_id on the root span
• log levels follow the shared convention[^levels]
• dashboards key off fields, never off message substrings

2026-03 - Single monorepo

We consolidated the previously separate service repos into one monorepo. The motivation was atomic cross-service changes and one CI pipeline; the cost is a heavier checkout, which we accept.

Attendees

Follow-ups

• migrate CI to a single pipeline (done)
• write a codeowners file so reviews still route correctly
• revisit checkout time in six months if it becomes a drag

[^pool]: Raising pool limits hides the real ceiling and tends to move the failure into the database connection layer, which is harder to recover from under load.

[^levels]: error pages a human, warn is reviewed at standup, info is for traffic-level narrative, and debug is sampled in production.

Demonstrates NoteThink's document view - deep heading hierarchy, nested and ordered lists, task lists, footnotes, strikethrough, blockquotes, and tables, all in one long-form note.