Architecture

App Router Structure

The project uses Next.js 15 App Router. All pages live under src/app/[locale]/ where [locale] is either us or uk.

src/app/
  [locale]/
    layout.tsx          # Validates locale, loads dictionary, wraps in SmartHeaderLayout
    page.tsx            # Home page
    about/page.tsx
    bills/
      page.tsx
      quote/page.tsx
    blog/
      page.tsx
      [slug]/page.tsx
    brand-ambassadors/page.tsx
    colleges/...
    lettings/page.tsx
    partners/...
    perks/...
    roomie/page.tsx
    students/...
    ...
  en-gb/
    student-accommodation/  # UK-specific filesystem routes (not rewritten)
      page.tsx
      [city]/page.tsx
      [city]/property/[id]/page.tsx
  api/
    assets/[resource]/      # GTM/Cookiebot proxy
    metrics/[script]/       # Analytics proxy
  studio/[[...index]]/      # Embedded Sanity CMS Studio

Locale System

Two locales: us (default) and uk. The locale list is defined in src/lib/utils/locale.ts as the LOCALES constant.

How Routing Works (No Middleware)

The locale system is implemented entirely through next.config.ts rewrites and redirects — there is no middleware.ts.

Public-facing URLs use /en-us/ and /en-gb/ prefixes. These are rewritten to internal /us/ and /uk/ paths that match the [locale] param:

/en-us/about    -->  rewrites to  -->  /us/about     (internal)
/en-gb/about    -->  rewrites to  -->  /uk/about     (internal)
/               -->  rewrites to  -->  /us           (internal)
/about          -->  redirects to -->  /en-us/about  (301)

Key rewrite rules in next.config.ts:

1. /en-us and /en-us/:path* rewrite to /us and /us/:path*
2. /en-gb and /en-gb/:path* rewrite to /uk and /uk/:path*
3. / rewrites to /us
4. Any bare path not starting with us|uk|en-us|en-gb|api|_next|images|favicon rewrites to /us/:path*

UK path renames: Some UK routes use different public-facing slugs:

UK student-accommodation routes (/en-gb/student-accommodation/*) are NOT rewritten — they are served by dedicated filesystem routes under src/app/en-gb/student-accommodation/.

Locale Validation

In src/app/[locale]/layout.tsx, the locale param is validated against the LOCALES array. Invalid locales trigger notFound().

const { locale } = await params;
if (!LOCALES.includes(locale as "us" | "uk")) {
  notFound();
}

Static params are generated for both locales:

export async function generateStaticParams() {
  return LOCALES.map((locale) => ({ locale }));
}

Locale in Client Components

Client components do not have direct access to the [locale] param. Instead, they derive the locale from the pathname:

import { getCurrentLocale } from "@/lib/utils/locale";
 
const locale = getCurrentLocale(pathname);

Feature Modules

Business logic is organized by domain under src/features/. Each feature can contain:

• components/ — React components
• actions/ — Server actions
• api/ — API call functions
• hooks/ — Custom React hooks
• types/ — TypeScript types
• helpers/ — Helper functions
• utils/ — Utility functions and constants

Complex features (with server actions, multi-step flows, or direct DB access):

• bills/ — 6 action subdirectories, multi-step checkout
• search/ — Direct MySQL queries with unstable_cache
• perk-partners/ — Finix payment integration

Simpler features (mostly UI components):

• about/, brand-ambassadors/, colleges/, lettings/, parents/, rideshare/, roomie/, universities/, rental/

API-only features (no components, just data fetching):

• property/, enquiry/, cities/, brochure/, agent-bookable/

Content features:

• location-content/ — Contentstack-powered location pages
• home/ — Home page header and components

Adding a New Page

Every new page requires two things:

1. Create the page file at src/app/[locale]/<path>/page.tsx
2. Add a RouteConfig entry in src/components/layouts/route-config.tsx

The RouteConfig controls the header, hero section, footer, CTA button, and region restrictions for the page. See Layouts for details.

Special Routes Outside [locale]

• /api/assets/[resource] and /api/metrics/[script] — GTM/Cookiebot proxy endpoints
• /studio/[[...index]] — Embedded Sanity CMS Studio (catch-all)
• /en-gb/student-accommodation/* — UK property search and detail pages (filesystem routes)