Introduction

1.1 Purpose

This document is the shared engineering standard for the frontend and backend teams. It exists because the two teams are being held to one reference for the first time: before this, decisions on structure, error handling, testing, and architecture were made independently per team, which made it hard to move engineers between teams, review each other’s code with confidence, or onboard new hires against a single source of truth.

The goal of this document is to remove ambiguity, not just describe tradeoffs. Wherever a decision is context-dependent, the relevant section gives a decision rule or checklist you can apply directly, rather than a list of considerations you have to weigh yourself every time.

Rule: if a section in this document leaves you unsure what to do in a real situation, that is a gap in the document, not a gap in your judgment. Propose a change using the process in 1.3.

1.2 Scope

This document covers how we build software: repository structure, code quality, frontend and backend architecture, engineering principles, state and data handling, error handling, security, performance, and testing. It applies to both teams equally. Where a rule is frontend-specific or backend-specific, the relevant section says so explicitly.

This document intentionally avoids naming specific tools as the only correct answer, with one exception: Section 2 documents the current approved stack as a fact, because engineers need a concrete, current answer to “what do we use today.” Every other section is written at the level of principles and decision criteria first, so the document keeps working if the stack changes later.

Deployment and CI/CD are explicitly out of scope. That pipeline is owned by a separate department. This document does not define build pipelines, deployment strategy, environment promotion, or release process, and it will not be extended to cover them. If you have a question about deployment or CI/CD, direct it to that department, not to this document.

1.3 Proposing a change to this standard

This standard is expected to change as the teams learn and the stack evolves. Treat it as a living document, not a fixed rulebook.

Every page on this site has an “Edit this page” link at the bottom of the table of contents. Click it to open the source file for that page directly in the repository, that is the fastest way to start a change.

To propose a change:

1. Open a pull request against this document with your proposed change.
2. State the reasoning in the PR description: what problem the current text causes, and why your proposed change solves it better than the status quo.
3. Get sign-off from the engineering lead before merging.

Rule: a change to this document is not valid until it has lead sign-off, regardless of how many other engineers agree with it informally. This keeps the standard coherent as a single reference, rather than a patchwork of locally negotiated exceptions.