Skip to main content

ADR 0001: Backend-First Development strategy

Date: 2025-02-20
Status: Accepted

Context​

Earlier project docs described Evalium as being built MVP-first with frontend and backend evolving together. As the scope grew (assignments, session runtime, snapshots, RLS tenancy, scoring, reporting), the backend became complex enough that front-end parallel development increased risk and slowed iteration.

Core concerns:

  • Need to guarantee correctness of multi-tenant RLS and snapshot logic
  • Avoid discovering architecture bugs only after building the UI
  • Increase iteration speed between backend and test suites
  • Prepare foundation for hiring additional backend engineers

Decision​

Evalium will adopt a backend-first development strategy:

  • Backend APIs, domain logic, migrations, RLS, and test suites must be implemented and validated before frontend work begins.
  • Frontend will only integrate once backend endpoints, behaviours, and invariants are stable.
  • All new features begin with:
    1. Schema design
    2. RLS policies
    3. TxManager-scoped behaviours
    4. API contracts
    5. Shell + Go integration tests
    6. Then frontend DX and UI work

Options Considered​

1. Parallel FE/BE development (previous model)​

Pros: Familiar, fast UI prototyping
Cons: FE built against unstable backend → rework, wasted time, bugs found late

2. Frontend-first prototyping​

Pros: Immediate UI validation
Cons: Impossible with Evalium’s backend complexity (assignments, silos, RLS, scoring)

3. Backend-first (chosen)​

Pros:

  • Strong internal guarantees
  • RLS + tenancy validated early
  • No frontend rework
  • Enables real test automation
  • Perfect for onboarding new engineers
    Cons:
  • Delays initial UI
  • Requires discipline on API contract documentation

Consequences​

Positive:

  • FE engineers get a stable API surface
  • Stronger backend correctness - Foundation built before scaling
  • Easier CI/CD adoption later

Negative:

  • Initial perception of slower progress
  • Requires permanent API documentation hygiene

Notes​

Updated README, architecture.NET, and TECHNICAL_FOUNDATIONS to reflect this philosophy. Frontend work begins only after backend delivers end-to-end operational correctness.