Architecture

Keep routes, layouts, and shared UI in the App Router structure of the application you are building.

Written for a Next.js 15 App Router application. Guidance for Next.js 16 bundled docs or /_next/mcp does not apply to 15.5.27.

Next.js project structure

What this describes

Buttons Navigation bars

Rules

NX-ARCH-001 required

Use the App Router

Pages live under app/. Do not add a second pages/ router beside it.

NX-ARCH-002 recommended

Use route groups for chrome

A route group can share a sidebar. A preview or print route can stay outside that group so it has no shell.

NX-ARCH-003 required

Build the control the screen needs

Match the documented element, color, and radius. Do not invent a second blue or a clickable div for an action.

NX-ARCH-004 recommended

Add error and loading boundaries when a route fetches

A route that waits on data can add loading.tsx and error.tsx. A static page does not need a fake loading state.

Correct

export default function SiteLayout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <nav aria-label="Primary"><a href="/records">Records</a></nav>
      {children}
    </div>
  );
}

Incorrect

export default function Page() {
  const section = 'records';
  return section === 'records' ? <Records /> : <Home />;
}

A section variable is not a URL. Each screen should be a route.

Checklist

The new page is a file under app/.
Shared chrome lives in a layout.
Actions are buttons and destinations are links.

AI instructions

You are implementing this practice in the current project. Do not install a design-system package and do not import one.
TASK: Apply Architecture.
Keep routes, layouts, and shared UI in the App Router structure of the application you are building.
APPLIES TO: Written for a Next.js 15 App Router application. Guidance for Next.js 16 bundled docs or /_next/mcp does not apply to 15.5.27.
RULES:
- NX-ARCH-001 [required] Use the App Router. Pages live under app/. Do not add a second pages/ router beside it.
- NX-ARCH-002 [recommended] Use route groups for chrome. A route group can share a sidebar. A preview or print route can stay outside that group so it has no shell.
- NX-ARCH-003 [required] Build the control the screen needs. Match the documented element, color, and radius. Do not invent a second blue or a clickable div for an action.
- NX-ARCH-004 [recommended] Add error and loading boundaries when a route fetches. A route that waits on data can add loading.tsx and error.tsx. A static page does not need a fake loading state.
CORRECT:
export default function SiteLayout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <nav aria-label="Primary"><a href="/records">Records</a></nav>
      {children}
    </div>
  );
}
INCORRECT:
export default function Page() {
  const section = 'records';
  return section === 'records' ? <Records /> : <Home />;
}
A section variable is not a URL. Each screen should be a route.
CHECK:
- [ ] The new page is a file under app/.
- [ ] Shared chrome lives in a layout.
- [ ] Actions are buttons and destinations are links.
SOURCE: Next.js project structure https://nextjs.org/docs/app/getting-started/project-structure
Build the interface with the project’s own markup. Match the documented colors and elements when a control is involved.
Do not upgrade Next.js to obtain bundled docs. Do not claim a WCAG audit. Do not add secrets.