> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing

> How routing works in your Archie app — pages, dynamic routes, navigation, and route protection.

Routing in your Archie app maps URLs to pages. The default stack uses Next.js App Router; other stacks use their respective conventions. The structure is generated from your blueprint's modules and your specifications' screens.

## Where routes live

Routes are defined by file structure. In a Next.js project:

```
app/
  page.tsx                  → /
  orders/
    page.tsx                → /orders
    [orderId]/
      page.tsx              → /orders/:orderId
  settings/
    layout.tsx              → wraps all /settings/* pages
    page.tsx                → /settings
    profile/
      page.tsx              → /settings/profile
```

Each `page.tsx` is a route. Each `layout.tsx` wraps its sibling pages and any descendants.

## Generated routes

When you build, Archie generates a route for every feature's screens. A blueprint module called "Orders" with screens "list", "detail", and "create" produces:

* `/orders` — list
* `/orders/[orderId]` — detail
* `/orders/new` — create

The route paths can be customized in the spec.

## Dynamic routes

Routes with parameters use bracketed segments: `[orderId]`, `[userId]`. Inside the page component, the parameter is available via the route hook (Next.js: `useParams()` or the `params` prop).

For nested resources (an order's items), nest the route file structure: `app/orders/[orderId]/items/[itemId]/page.tsx`.

## Layouts

Layouts wrap a group of routes with shared structure: a sidebar, a header, an authentication guard. The default layout in `app/layout.tsx` wraps the whole app. Per-section layouts wrap subsections.

To add a layout: create `layout.tsx` in the relevant directory. Anything you render inside it (the sidebar, the header) appears on every page within that directory.

## Navigation

Internal navigation uses the framework's link component (Next.js: `<Link>`). The chat and visual editor handle wiring up navigation when you add a button that should go somewhere.

For programmatic navigation (after a form submit, after a delete confirmation), use the framework's router hook (Next.js: `useRouter()`).

## Route protection

Pages can require authentication, a specific role, or a specific permission. Protection is configured in two places:

* **Spec-level** — the spec marks which user types can access each screen. Generated code enforces this.
* **Code-level** — for fine-grained checks, edit the page or layout and call the auth utilities (`useAuth`, `requireRole`).

Protected routes redirect unauthenticated users to the sign-in page. See [Connecting to the backend](/features/frontend/connecting-to-the-backend) for the auth flow.

## Catch-all and 404

The app has a built-in 404 page in `app/not-found.tsx`. To customize it, edit that file or describe the change in the chat.

For catch-all routes (rare), use `[[...slug]]` segments. Useful for documentation sites, marketing pages, and CMS-driven content.

## Sitemap and SEO

For public-facing apps, generated routes include `<title>` and `<meta>` tags from the spec's screen-level metadata. To add OG tags, structured data, or canonical URLs, edit the page's metadata export. The framework handles the rest.

A sitemap.xml generates automatically, listing all public routes. Customize it by editing `app/sitemap.ts`.