You just bought it

Project structure

A screen is three files. The rest of the tree exists so those three stay short.

Add a screen: three files

Everything else follows from these. A screen is a route, a row in the menu, and whatever the page renders.

the three

app/(shell)/customers/page.tsx   the screen itself
app/nav.ts                       one row, so it is reachable
app/(shell)/customers/data.ts    its type and fields, if it is a record screen

Why the route groups

(shell) and (auth) are Next route groups: the parentheses mean they are not part of the URL. app/(shell)/customers/page.tsx is served at /customers.

(shell) has the sidebar, the header and the scroll container. Almost everything lives here.
(auth) has no shell: a sign-in screen with a sidebar is a sign-in screen for somebody already signed in.

The group also decides what a buyer receives. The free download is packed from this application by removing the paid routes, and a route's directory goes whole, so a shared module belongs inside the directory that uses it rather than one level up.

Where the rest is

Path	What decides it
app/nav.ts	The sidebar, the breadcrumb trail and the command palette
app/shell.tsx	The frame: sidebar, header, footer, scroll container
app/layout.tsx	Fonts, metadata defaults, the theme script
src/vui/theme.css	Every token. Change one, move everything
src/vui/*.tsx	One component family each

⚠️ A client screen cannot export metadata

Next forbids it. If your page starts with "use client", put its metadata in a sibling layout.tsx. Page types 3 to 5 are client pages, so this is the common case rather than the exception.