Skip to content

Start from defined architecture, not from an empty repository.

Next.js · React · TypeScript

Foundation is a configuration-first website base with a framework-independent core, ports and adapters, schema-validated configuration and a real verification gate. You inherit the fundamentals and spend your time on the parts that are genuinely specific to the site you are building.

  • Next.js App Router with React Server Components
  • TypeScript throughout, with schema-validated configuration
  • Unit, architecture and real-browser gates in the repository

Architecture at a glance

Four stages with a one-way dependency direction. The middle two are the foundation; the first and the last are yours.

  1. Site data, content and assets

    Identity, navigation, locales, Markdown content and artwork — the adopter-owned inputs, validated before anything reads them.

  2. Foundation-derived runtime

    Framework-independent domain concepts plus the application services that orchestrate them, with no framework imports of their own.

  3. Presentation, routing and integration seams

    Routes, layout composition, metadata, and the adapter factories that bind booking, enquiry, maps and analytics from configuration.

  4. Deployment

    A static-generation-first build deployed from your own repository to your own hosting account.

Dependency direction is asserted by tests rather than assumed: the core may not import React, Next.js or an outer layer, and the application layer may not reach into a concrete adapter.

Configure, or code

This boundary is the point of the project. Most business-specific decisions are data; genuine extensions are code, and Foundation is explicit about which is which.

Usually configured or authored

  • Identity: name, tagline, description and canonical URL
  • Navigation, and the secondary/footer group
  • Locale set and interface dictionaries
  • Business regions, opening hours and directions
  • Content: pages and collections as Markdown
  • Branding, icons and imagery
  • Provider selection for booking, enquiry, maps and analytics
  • Feature enablement for offerings, portfolio, blog and testimonials
  • Presentation values the configuration contract exposes

Requires code when genuinely extending behaviour

  • A new provider adapter for an existing capability
  • A new reusable capability
  • New UI behaviour or interaction
  • A new downstream application module
  • Anything outside the established configuration boundaries

The approved position: most business-specific identity, content, branding and feature selection live outside the application core. That is not a promise that no code is ever written — a genuinely new capability is platform work, and Foundation says so rather than implying a plugin system exists.

The engineering contract

What the project holds itself to — and what it refuses to claim.

  • Strict validated configuration

    One schema, unknown keys rejected, actionable failures, and configuration readable only through the loader.

  • Hexagonal boundaries

    A pure core, application ports and services, adapters behind factories, and thin framework routes.

  • Dependency enforcement

    Architecture tests walk the source tree and fail on a forbidden import, so the diagram cannot drift away from the code.

  • Server-first composition

    React Server Components and static generation by default, with client interactivity confined to the components that need it.

  • Real-browser verification

    A committed headless-browser matrix drives desktop, tablet and mobile widths, keyboard and pointer interaction, reduced motion and dark scheme, and fails the run on any assertion failure.

  • Architecture and unit gates

    Boundary and unit tests run beside the assets check, type check, lint and production build.

  • Capability-claim discipline

    Documented capability claims are checked against the project's own record of what is implemented and verified, so a claim cannot be raised above its evidence.

  • An honest upgrade model

    Because your configuration, content and assets live outside the application core, platform improvements can be absorbed instead of overwriting your work.

What the project does not claim

Foundation does not claim WCAG conformance, a security certification, penetration testing, published performance or Lighthouse scores, or universal browser and device coverage. Accessibility and performance are engineered and verified where the project is able to verify them — they are not certified.

Where Foundation stops

The same ownership split, stated technically. Foundation deliberately stops before business operational complexity, and provides the seam to whichever service you choose.

Adopter-owned

  • Configuration
  • Content
  • Locale dictionaries
  • Business artwork
  • Provider choices
  • Downstream extensions

Foundation-owned

  • Application architecture
  • Reusable UI machinery
  • Configuration validation
  • Routing and content machinery
  • Integration seams
  • Verification infrastructure

Extension works from the outside in: a new provider is an adapter plus a factory branch and a schema enumeration entry, and a new content type or locale is data. A genuinely new capability is platform work.

Adoption workflow

Eight stages. The repository owns the command-level detail — this is the shape of the work.

  1. Get Foundation

    Clone or fork the public repository.

  2. Install and run

    Install dependencies and start the site locally.

  3. Configure

    Set identity, locales, features and provider choices.

  4. Author content and assets

    Write your pages and replace the brand asset roles.

  5. Connect providers

    Point the seams at the services you actually use.

  6. Validate

    Run the project's own gate locally.

  7. Deploy

    Build and deploy from your own repository and account.

  8. Maintain and upgrade

    Absorb upstream improvements without overwriting your material.

The repository's instruction manuals cover each stage, including troubleshooting.

Authoritative documentation

GitHub is the canonical technical source. This website summarises; the repository instructs.

  • Repository

    The complete source, its licence, and the project's own statement of what it is and is not.

  • README.md

    What the project is, quick start, repository layout and the licence position.

  • ARCHITECTURE.md

    Architectural style, boundaries, dependency direction and integration patterns.

  • CUSTOMIZING.md

    The downstream user guide and the complete configuration reference.

  • DEPLOYMENT.md

    The launch runbook and the post-deployment verification checklist.

  • BRAND_ASSETS.md

    The brand-asset swap contract: every replaceable graphic role.

  • Instruction manuals

    Adoption, customisation, branding, content, upgrade, validation, deployment and troubleshooting procedures.

Every destination above is a link into the public repository, which is where those documents are maintained.

Read it, run it, change it

The code, its tests and its documentation are the argument. Start there.