Engineering.
This is how the PerkUp engineering team works — how we get set up, how we operate day to day, and how we ship. It is deliberately not a tour of the codebase: the code is the source of truth for how things work. This section is the source of truth for how we work.
New here? Start here
How we operate
A few principles describe most of how the team makes decisions. They're the through-line behind the tooling and the pipeline:
- The repo is the source of truth. Conventions live in
AGENTS.mdfiles next to the code they govern, and change in the same PR as the code. When docs and code disagree, the code wins. - Trunk-based and continuous. Short-lived branches off
main, small PRs, merge often. Merging tomaindeploys — there is no separate release train to wait for. - Automate the gate, not the gatekeeper. CI and inline review bots catch the mechanical stuff so human review can focus on intent. Run the checks locally first.
- Fix forward. Because deploys are small and fast, the default response to a bug is a quick follow-up PR, not a heavy rollback.
- Bias to the simplest place. New backend work goes to Cloud Functions (TypeScript); the Go service is in maintenance mode. One frontend SPA, one set of shared packages.
The operating model above is reconstructed from our CI configuration, deploy jobs, and repo conventions — it describes how the system is set up to work, not a formally ratified policy doc.
Explore
Getting Started
From zero access to your first merged PR.
Developer Environment
Local setup, the toolchain, and the inner-loop cycle.
How We Ship
CI, deploys, deployment speed, and bug fixes.
Architecture
The high-level shape of the system and its key concepts.
Testing
How we think about tests and where they belong.
Integrations
What we connect to and how those connections are shaped.
Runbooks
What to do when something breaks.
Source: repo conventions in perkup-app (CLAUDE.md + per-directory AGENTS.md), CI/CD configuration, and team practice. Compiled 2026-06-07.