Solution design

Non-trivial changes go through a design phase before code is written. The phase produces written artefacts that record what is being built and why, and an explicit approval before the work moves to delivery.

Inputs

• Product brief. A PRD or Pitch document in Google Drive describing the problem, the proposed solution, and the success criteria. Authored by Product, reviewed with Engineering.
• UI mockups. Drafted in Miro and usually embedded into the Drive doc so reviewers see one artefact rather than two.
• Architecture draft. An Architecture Decision Record (ADR) in the relevant GitHub repository, opened as a pull request in proposed status. The ADR captures the context, the options considered, and the chosen decision.

Tracking

Each design phase has a Jira ticket. The ticket links to the Drive doc and the ADR pull request. Discussion and decisions made during review are recorded as comments on the ticket so the trail is preserved when the ticket closes.

Approval

A design is approved when:

• The Drive doc is reviewed by Product and Engineering and any comments are resolved.
• The ADR pull request is approved and its status is updated from proposed to accepted.
• The Jira design ticket is transitioned to Done.

The ADR is then merged to main. Implementation work proceeds against the approved design; further changes that contradict the ADR require a follow-up ADR.

What gets an ADR

Anything that introduces a new external dependency, changes the data model, changes how data flows between services, changes an authentication or authorisation boundary, or commits the team to a particular technology long-term. Routine refactors, bug fixes, and small features that fit cleanly into existing patterns do not need one.

What an ADR looks like

ADRs follow Michael Nygard’s format:

# N. Title

Date: YYYY-MM-DD

## Status
Proposed | Accepted | Superseded by N

## Context
What's the situation, what's driving the decision.

## Decision
What we're going to do.

## Consequences
What becomes easier or harder; what trade-offs we accept.

The ADRs already accepted in the platform repo at docs/adr/ are useful references for format and depth.

Security considerations

As you design, think about how the change might be attacked, broken, or misused, and capture the points that matter in the ADR. Things to cover:

• Threat modelling. Walk through how the change could be attacked or misused. Martin Fowler’s site has a good piece on agile threat modelling if you want a structure.
• Data flows. When your design changes how data moves between services or where it’s stored, sketch the data flow as part of the design. Especially worth doing for sensitive data.
• Multi-tenancy. If your design touches data or access, think about how it preserves the per-tenant boundary. Row-level security at the database and integration tests catch breaks before they ship; thinking about it up front will save you time.
• Privacy. If you’re capturing, processing, or transmitting personal data, name it in the design (PII, PHI, or whatever category fits) and think about how it’s handled.
• Reversibility. Lean toward reversible designs. If a change is irreversible (schema migration, data deletion, irrevocable side effect), plan a validation strategy first (dual-write or shadow reads) before cutover.
• Secure defaults. New API surfaces are authenticated by default. If you have a reason to make a route unauthenticated, that’s a design decision worth capturing in the ADR.