Skip to content

Engineering Charter

This is the engineering team's commitment to how we build, ship, and operate the someli-api platform. It is signed by engineering leadership and binding on every contributor.

The charter sets the principles. The specifics — what code style, what tools, what tests — live in engineering-practices.md. The pre-merge checklist for each PR lives in definition-of-done.md.

When there is an argument about whether something needs to follow a practice, this document is the authority that says yes, it does.

Why this exists

We are running two streams of work at the same time:

  1. A feature stream that builds product capabilities customers pay for.
  2. A refactor stream that pays down the technical and operational debt accumulated while the platform was getting product-market fit.

These two streams will collide unless the feature stream operates under the same standards the refactor stream is establishing. Otherwise, the refactor stream is paying down debt the feature stream is producing — and never catches up.

This charter exists to prevent that collision. The principles below apply to all code being written or modified, regardless of which stream it belongs to.

Our commitments

We commit to the following:

1. Every change is reviewed before it merges

No engineer self-approves. PRs require at least one review (two for security, billing, and authentication paths). Branch protection enforces this.

2. New code is tested, typed, and observable

We don't add to debt deliberately. New code includes: - Tests sufficient to verify the behavior - TypeScript with strict types (no any without explicit justification) - Structured logging (no console.log)

Existing code that doesn't meet these standards is grandfathered, but every time we touch it, we improve the part we touch (the boy-scout rule).

3. New endpoints are specified before they're implemented

The OpenAPI spec is the contract. The API surface is not a private convenience for the team that wrote it; it is a public commitment to the team that consumes it.

4. Database schema changes go through a migration file

Manual ALTER TABLE in any environment is forbidden. Migrations are versioned, reviewed, and run identically across dev / staging / prod.

5. Secrets never enter source code

Hardcoded credentials in a PR fail review automatically. Pre-commit hooks scan for them. We rotate any secret that has ever been in git history.

6. Every job claim is idempotent

Retries do not double-charge customers, double-post to social platforms, or duplicate data. Idempotency keys are mandatory on any operation with external side effects.

7. We measure what we ship

Every new endpoint emits structured logs and metrics. Every job emits start / success / failure events with correlation IDs. We don't ship behavior we can't see.

8. We don't grow files past 1,000 lines

We split before we add. The 21,000- and 24,000-line route files are the consequence of repeatedly violating this rule. We will not produce another one.

9. Touching a legacy file for a feature includes upgrading the part you touch

Extract the handler you're modifying into the appropriate module. Add a test for it as you extract. The legacy code shrinks every time someone visits it.

10. New external dependencies require a justification

We default to "no." Adding a package because "it's easier than writing 30 lines" is not a justification. We carry an npm audit-clean dependency tree.

11. Boring code is good code

We resist clever-but-fragile contributions. We prefer obvious, debuggable, predictable code over elegant abstractions that nobody else can maintain. Cleverness is a deferred maintenance cost.

12. We close incidents with practice-level fixes

After every Sev-1 / Sev-2 production incident, we ask: which practice would have prevented this? If the answer is "we don't have one," we add one to engineering-practices.md. We don't just close the bug.

How this is enforced

Three concentric tiers of enforcement, from strongest to weakest:

Tier Mechanism Examples
Automated gates Lint rules, CI checks, branch protection, pre-commit hooks No-secrets, no-console.log, lint clean, tests pass, ≥1 review
Process gates PR template, CODEOWNERS, ADR requirement, release checklist Definition of Done checklist, sensitive-path reviewers, design decisions captured
Cultural gates This charter, onboarding, postmortem culture, recognition "Boring code is good code"; tech-debt rotation; blameless review

Tier 1 is what we rely on most. Humans forget; CI doesn't. We invest in tooling that makes the right thing the easy thing.

When a practice exists but isn't yet automated, it relies on Tier 2. The expectation is that Tier 2 practices migrate to Tier 1 over time as we build out the tooling.

Tier 3 is what makes the difference between a team that follows the practices and a team that owns them.

Adoption schedule

The full set of practices is not adopted on day 1 — that produces revolt. They are adopted in waves, each wave closing before the next opens. See engineering-practices.md §Adoption Waves for the schedule and gating criteria.

The current wave is tracked in verify-markers.md.

Authority and exceptions

This charter is the authority that engineers can cite when they are pushed to skip a practice for short-term reasons.

When a practice genuinely needs to be skipped — and there are legitimate cases — the exception process is:

  1. Document the reason in the PR description (what, why, what we'll do instead).
  2. Add a follow-up issue to address the gap.
  3. Get the exception approved by an engineering lead, not just any reviewer.
  4. Time-box the exception — exceptions that age past 30 days without resolution are escalated.

Exceptions are not the failure mode we're trying to prevent. The failure mode is silent non-compliance: a practice exists, nobody talks about it, code merges that violates it, and a year later the codebase is full of violations nobody acknowledged. Explicit exceptions with follow-up issues are healthy. Silence is not.

Review and revision

This charter is reviewed annually and updated when:

  • A new principle becomes load-bearing (a maturity-model pillar advances)
  • An existing principle no longer matches reality (a practice is changed or retired)
  • A postmortem reveals a missing principle

Updates are themselves PRs reviewed by engineering leadership.

Signatures

[VERIFY] Sign-off names — to be added by engineering leadership when adopting this charter. The signatures matter not as legal artifact but as the moment the team commits.

Role Name Date
Engineering Lead _____ _____
Tech Lead — Backend _____ _____
Tech Lead — Platform / Infra _____ _____
Tech Lead — Frontend _____ _____