Skip to content
bflo.sh

ADR-0004: Application stack — Laravel backend, Next.js frontend

ADR-0004 — Accepted (template baseline). Part of the platform's decision record.

Adapted from the repo's docs/adr/0004-application-stack.md — Part of Internals: the platform's design set, published as content on the platform it describes.

  • Status: Accepted
  • Date: template baseline
  • Deciders: template authors
  • Tiers affected: backend, frontend, infra
  • Related: ADR-0003 (environment baseline)

Context

This template line fixes the application stack, so projects start with zero stack deliberation and share conventions across projects. The environment baseline beneath it (DDEV + PostgreSQL 16 + Redis) is ADR-0003.

Decision

  • Backend: PHP 8.5 · Laravel 13.x (13.18.1 installed) in backend/, layered Http → Domain → Data; DDEV project type laravel (docroot backend/public, composer root backend).

    Notation note (2026-07-05): "13.5" in the original baseline was shorthand for the 13.x line, not a hard pin; the current skeleton resolves laravel/framework: ^13.8 and composer create-project installs 13.18.1 (latest 13.x). The decision — Laravel 13.x on the backend — is unchanged; only the notation is corrected to the attainable version.

  • Frontend: Next.js in frontend/, served by the dedicated frontend (Node 22) DDEV service; consumes the API only through clients generated from contract/openapi.yaml.

Alternatives considered

  1. Per-project stack choice — maximal flexibility, but this template deliberately trades it for zero spin-up deliberation; teams needing a free stack choice should start from a stack-agnostic template instead.
  2. SPA without an SSR framework (plain Vite/React) — loses the routing/SSR/data conventions Next.js standardizes; rejected.
  3. Blade/Inertia monolith — couples the tiers this template deliberately walls apart; rejected.

Consequences

  • Members may assume Laravel and Next.js idioms inside their tiers without asking.
  • The frontend never imports backend types directly — only clients generated from the contract.
  • Framework upgrades are baseline changes: new ADR plus coordinated adoption tasks.

Compliance

  • infra/ddev/bootstrap.sh configures DDEV type laravel; review rejects application code outside backend/ and frontend/.
  • Tier verify commands run per stack inside DDEV (see CLAUDE.md → Definition of done).