Skip to main content

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 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. 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 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.