en
EnglishSvenskaDeutschNederlandsFrançaisEspañolItaliano

Lunover Engineering Notes

How to Structure a Web Agency Codebase for Scale

A scalable architecture pattern for agency delivery: content boundaries, reusable sections, deterministic routes, metadata helpers, and internal-link rules.

February 10, 2025By LunoverWork with us

How to Structure a Web Agency Codebase for Scale

If every new page requires a new page component, an agency codebase becomes a bottleneck. The fix is not "more components". The fix is a strict content model, predictable routing, and reusable page sections that stay SEO-safe as the site grows.

What you're optimizing for

  • fast shipping without layout drift
  • fewer regressions in navigation/SEO
  • predictable content publishing
  • easy internal linking between articles and services

1. Separate content from rendering

A simple rule that scales: content lives in MDX (or a CMS), rendering lives in components. Content should contain:
  • title, description, slug
  • optional publish date and image
  • page-specific data (FAQs, testimonials, feature bullets)
Rendering should contain:
  • hero layout
  • section layouts
  • typography and spacing
  • shared CTA patterns
This prevents the "copy/paste page" trap.

2. Standardize your section system

Define a small set of sections and reuse them everywhere:
  • Hero
  • Services grid
  • Process steps
  • FAQ
  • CTA
  • Testimonials
Make sections data-driven so content changes do not require layout changes.

3. Keep routing deterministic

Predictable route families let you automate SEO safely:
  • /services/[slug]
  • /blog/[slug]
  • /legal/[slug]
When routes are consistent, you can generate:
  • canonical URLs
  • alternates/hreflang
  • sitemap entries
  • schema output
without custom code per route.

4. Centralize metadata generation

Metadata is not a copywriting detail. It is infrastructure. Put canonical/hreflang/robots logic in one helper and reuse it across routes. If your site is multilingual, alternates must be derived from real content availability, not string substitution. See: Next.js 16 SEO Checklist for Production

5. Treat internal links as architecture

Internal links are how you connect technical authority to commercial intent. A rule that works well for agency sites:
  • every technical post links to one relevant service page
  • every service page links to one relevant technical post
Start with these anchors: Then build clusters:
  • SEO implementation posts -> /services/seo
  • performance/Next.js posts -> /services/web-development

6. Recommended folder layout

Example (App Router + MDX): 
src/
  app/
    [locale]/
      (pages)/
        blog/
          [slug]/page.tsx
        services/
          [slug]/page.tsx
  lib/
    seo-helpers.ts
    mdx-helpers.ts
  markdown/
    en/
      pages/
      blog/
The goal is one consistent path from:
  • content -> route -> metadata -> schema -> sitemap

7. Publishing checklist (non-negotiable)

Before a page goes live, confirm:
  • frontmatter is present (title, description, slug)
  • page has a clear primary intent
  • canonical URL is correct
  • internal links exist (to services and related articles)

Related