Frontend Structure

Three parts give every file one home by answering one question: is it cross-cutting, is it an address, or does it serve one use case. Without the split, shared values hide inside routes, use-case code hides inside shared folders, and no author can tell where a new file belongs. The three parts make the answer mechanical.

Each stack names these three parts for its own toolchain.

{frontend}/
  frame/     client configuration, session, language, permissions, formatting, shell data
  routes/    one entry per address
  modules/   one folder per backend module, aggregate, and use case

Reviewed forWhich frontend files sit outside the frame, routes, and use-case modules split? Look in the frontend folder roots.

Marked guidance: a reviewer answers this question.

A reader holding a specification page finds the frontend code by translating three names to lowercase folders. No second map, index, or naming register stands between the specification and the code, so an agent given a use case id resolves its frontend folder by rule. The backend holds one folder per use case, so the mirror names one folder. The frontend structure test holds the mirror on every build under litespec/frontend/testing#prove-the-module-mirror-in-a-structure-test.

One backend folder and its frontend counterpart are the same path in two spellings.

<backend>/Orders/Orders/UseCases/SearchMerchantOrders/
<frontend>/modules/orders/orders/search-merchant-orders/

For example, the Claimwick product lists expenses through use-case/spending.list-expenses, implemented in the backend under Spending/Expenses/UseCases/ListExpenses. The web frontend serves it from the same path in kebab case: lib/modules/spending/expenses/list-expenses in the Claimwick example, beside the screen record screen/claimwick-app.expense-list.

<backend>/Spending/Expenses/UseCases/ListExpenses/
<frontend>/modules/spending/expenses/list-expenses/

The three backend names become three lowercase folder names, so a reader holding the use case finds the frontend code by translating Spending, Expenses, and ListExpenses. The UseCases/ segment carries no frontend spelling.

A query that describes no one aggregate has its record home under use-cases/ beside its module, so its folder mirrors that home with two names instead of three: a query named use-case/spending.read-spending-summary would live at <frontend>/modules/spending/use-cases/read-spending-summary/ and <backend>/Spending/UseCases/ReadSpendingSummary/. The running Claimwick example holds no such module-level query.

The diagram shows the backend path beside its frontend mirror, with one arrow per translated segment.

Reviewed forWhich use-case folders sit outside {module}/{aggregate}/{use-case}/ in kebab case, or resolve to no backend folder of the same names? Look in the module tree and the structure test proving the mirror.

Marked guidance: a reviewer answers this question.

A subfolder inside a use case folder names a grouping the backend does not have, so the one-to-one mirror between the two trees stops at that point. Past the subfolder, the reader can no longer translate names by rule, and nothing reports where the translation broke. Files directly in the use case folder keep the mirror checkable to the bottom.

Reviewed forWhich use-case folders hold a subfolder? Look in the module tree.

Marked guidance: a reviewer answers this question.

A file read by several use cases of one aggregate belongs flat in that aggregate's folder: the lowest folder holding every reader. There it sits beside its consumers, found by browsing rather than through an index, and moving it changes nothing outside the aggregate. A file read by several aggregates rises one more level, to the module folder, by the same rule.

Three expense queries share one tab strip, so the tab strip sits flat in the aggregate folder. A file read by several aggregates sits flat in the module folder.

Reviewed forWhich files read by several use cases sit outside the narrowest folder holding every reader? Look in the aggregate and module folders.

Marked guidance: a reviewer answers this question.

A folder named shared, utils, or components can refuse nothing: every author with a file of unclear ownership drops it there. The folder collects unrelated code that escapes review against the use cases it serves, and finding a file means searching a pile instead of translating a use case path. The refused names force each file into the folder that owns it. The rule covers an application's src, not a shared package's internals, which the package owns.

A shared query three use cases read sits flat in the aggregate folder, not in a shared/ folder beside them.

Reviewed forWhich folders under an application's src carry a refused name? Look in the application folder tree.

Marked guidance: a reviewer answers this question.

A route entry serves one address: its input, its load, and its component. A column definition or validation rule written there is unreachable from the second route that needs it, so the second route writes its own copy. A reference from one route entry to another makes one address depend on another, so changing the first breaks the second. Reusable logic belongs in modules, where both routes import it.

An expense list route validates its search, prefetches its read, and composes one screen from module components.

Reviewed forWhich route entries hold reusable logic or reference another route entry? Look in the route entries.

Marked guidance: a reviewer answers this question.

The route is where a screen record becomes code, and its folder or file name only resembles the screen. One mark makes the link written and checkable: a web route exports the same typed litespec constant a use-case module exports, so a wrong identifier fails the consumer's type check against the generated union, and litespec model check reports it as mark-unknown where no type check ran, and a Blazor component or an Android destination carries the .NET mark the .NET reader already reads. Each stack page states its route entry, the file or class that carries the mark, and that layouts, error pages, and route groups are not route entries: the Svelte Stack, React Stack, Blazor Stack, and Android Stack pages state theirs. The use cases a screen offers are not marked on the route; the builder computes them from its calls.

The <script module> of the Claimwick expense list page exports export const litespec = { implements: "screen/claimwick-app.expense-list" } as const satisfies LiteSpecMark;.

Checked bylitespec model check reports mark-missing (level S) for a route entry with no mark, mark-count-invalid (level S) for one with more than one, and mark-unknown (level S) for a mark naming no screen of the route's entry point.

Marked checkable: the tool named here checks it.

Imports pointing from routes to modules to the frame to shared packages keep addresses, use-case code, cross-route values, and shared code in separate layers. A reverse import collapses two layers: a module importing a route ties use-case code to one address, and a shared package importing an application ties every application to one application's choices. One direction keeps each layer usable without the layers above it.

This direction shows the allowed dependency path.

Routes -> modules -> frame -> shared packages

The direction refuses three imports: a module reaching a route, a shared package reaching an application, and a frame module reaching into one module's use-case folder for a second module's data.

Reviewed forWhich imports point against the route to module to frame to shared package direction? Look in the import statements.

Marked guidance: a reviewer answers this question.

Each application owns its routes, its environment, its session handling, its words, its tests, and its deployment, so it can change, test, and ship on its own. An import from another application's source ties the two together: a change to one breaks or redeploys the other. Code two applications genuinely share moves down into a shared package, which names neither application.

Reviewed forWhich frontends import source from another frontend? Look in the import statements.

Marked guidance: a reviewer answers this question.

Shared packages hold what serves every frontend and names none of them: the generated client, the shared UI package, the locale dictionaries, and the frontend tooling. Page composition, feature state, authentication policy, or application components kept there would bind every application to one application's choices. Application-specific code stays in the application, where it can change without touching the rest.

Reviewed forWhich shared packages hold page composition, feature state, authentication policy, or application components? Look in the shared package sources.

Marked guidance: a reviewer answers this question.

Client configuration, session read, language choice, permissions, formatting, and shell data cross every route. A route holding one of them holds a copy beside every other route's copy, with nothing keeping the copies equal. The frame holds each once, where every route reaches it. A browser API a use-case module needs belongs in the frame too, because a module renders and reads data rather than touching the device.

Reviewed forWhich client configuration, session read, language choice, permissions, formatting, shell data, or browser uses sit outside the frame? Look in the frame.

Marked guidance: a reviewer answers this question.