Orca ORCA v0.174.2
Welcome Developer Guide Infrastructure Platform Engineering Runbooks Archive
Documentation navigation

Working on the AI Platform

Welcome! These articles give you a high-level mental model for how code goes from "an idea" to "running software that your colleagues actually use". You don't need to memorise any of this — just know that each step exists and what it's roughly for.

The journey from idea to live

Every change you make follows the same path. The diagram below shows the big picture; the rest of these articles zoom into each box.

graph LR
  A[Idea] --> B[Code]
  B --> C[Pull Request]
  C --> D[CI checks]
  D --> E[Merge]
  E --> F[Released to users]

What each step is for

  • Code — you edit files on a feature branch (using your editor, tools, or AI assistance).
  • Pull Request — you propose your change on GitHub so others can review it.
  • CI checks — tests and builds that GitHub runs on every PR, using workflows our platform team has defined.
  • Merge — once approved, your change joins the main codebase.
  • Released — Orca picks up the new build and deploys it to a live environment.

Why this process exists

We don't edit files directly on the live server for four reasons. Safety — every change goes through a series of automated checks, so most mistakes get caught before they reach users, and the ones that don't are easy to roll back. Collaboration — others can see what you're proposing before it goes live, and you can see (and learn from) what they're proposing. Traceability — every change has an author, a timestamp, and a reason attached to it, so when something behaves unexpectedly six months from now, we can find out exactly when and why it changed.

Compliance is the fourth reason, and for us it's not optional. We're certified under compliance frameworks (such as ISO 27001 and SOC 2) that require code reaching production systems to have been reviewed by at least one person other than the author. Every PR you open, every review you receive, and every merge that happens is recorded in GitHub's audit log as evidence that this happened. There are narrow exceptions — for example, an emergency hotfix — but they need a good documented reason and the audit log still has to capture who did what. In practice this means: never merge your own un-reviewed PR, no matter how small it looks. It's not bureaucracy; it's the deal that lets our customers trust us with their data.

How AI agents fit in

Claude Code writes the code, but you own the change. You decide what to build, you review what the agent produces, and you press the buttons that move it through the process. The agent is a tool, not a substitute for your judgement.