Project structure

Where things live and which parts belong to which surface.

Routes are grouped by surface. A route group in parentheses does not appear in the URL, so (landing)/about/page.tsx serves /about.

Txt

src/
  app/
    (landing)/     marketing site: home, pricing, blog, legal
    (product)/     signed-in shell: dashboard, analytics, users, settings
    (auth)/        sign-in, sign-up, password reset
    (docs)/        this documentation engine
    api/           route handlers (og image generation, profile)
    layout.tsx     the one root layout, shared by every surface
  components/      shell components: Providers, UserProvider, CustomMDX
  content/         MDX and data objects, one directory per content type
  lib/             server-side helpers: errors, docs loader, Supabase
  resources/       tokens, icons, SEO metadata, validation rules
  utils/           small shared helpers

The shell

src/app/layout.tsx, src/components/Providers.tsx, the token config in src/resources/once-ui.config.js and the error contract in src/lib/errors.ts are always present. Every surface renders inside them.

Surfaces

Each route group is a surface: a self-contained feature area that can be included or left out. Surfaces declare which capability slices they need — (product) needs auth, (landing) and (docs) need nothing.

Content

src/content mirrors the surfaces. Blog posts and legal pages belong to the landing surface, documentation pages to the docs surface, and brand and navigation data to the shell because the root layout reads them. Read Surfaces and slices for the rules that keep this separation honest.

Last updated August 27, 2026

Edit this page on GitHub