Workspace Structure

Requirement A consumer workspace MUST use the canonical root tree declared in this section.

Example Consumer workspaces use this shape:

{repo}/
  .config/
    <tool manifest>
  .model/                      generated; ignored
  apps/
    api/
      <backend project manifest>
      src/
      tests/
    {frontend}/
    apphost/                   when one host runs more than one application
  packages/
  docs/
    product/
      brief.md
      {area}/                  product topic pages carrying requirement entries
      constraints/             create with the first constraint record
      decisions/
      features/                create with the first feature record
      journeys/                create with the first journey record
      problems/                create with the first problem record
    research/                  create with the first research record
    domain/
      README.md
      actors/
      roles/
      permissions.md
      entry-points.md
      modules/
        {module}/
          README.md
          {records-plural}/
            README.md
            {use-case}.md
      rules/                   create with the first cross-record rule set
    operations/                create with the first operating record
      limits.md                create with the first limit record
      secrets.json             create with the first secret
      log/                     create with the first operations entry
    runbooks/                  create with the first runbook
    exceptions/                create with the first exception record
    known-gaps/                create with the first known-gap record
    ui/                        create with the first UI decision or guide, held in the pattern catalog and the design contract
    language.json
  litespec/
  AGENTS.md
  <toolchain pin file>
  package.json                 when a frontend or TypeScript package exists
  pnpm-lock.yaml               when a frontend or TypeScript package exists
  pnpm-workspace.yaml          when a frontend or TypeScript package exists
  litespec.project.json

A backend stack binding names the files that realize the entries in angle brackets.

The example places neither the backend application nor a frontend application at the workspace root. Under modules/, each module folder holds one folder per business record in plural kebab-case form.

A record page lives at the home the tree names for its type. An entry lives on its home page. Requirements live on product topic pages, permissions on the permissions page, entry points on the entry-point page, and limits on the limits page. Rules, results, cases, and events live on their business record or use case page.

Requirement litespec.project.json MUST declare size as small or large and one stack for the backend and for each frontend.

Rationale Size decides which record types and test projects apply, and each stack decides which technology pages and checks apply.

Requirement The generated .model/ folder MUST stay out of source control.

Rationale The model builder writes model.json there from records, code, routes, tests, and test runs, so the folder is rebuilt rather than reviewed.

Requirement Production code MUST live under apps/api/src/ and test code under apps/api/tests/.

Rationale The split makes a test dependency reaching production code visible in the path itself.

Example The backend tree is:

apps/api/
  <backend project manifest>
  src/
  tests/

Requirement An independently runnable frontend, API, or deployed host MUST live under apps/{name}/.

Rationale A reusable package under apps/ or deployable code under packages/ inverts what each root promises.

Requirement A shared TypeScript package MUST have at least two consumers or carry generated output shared by design.

Rationale The baseline permits shared configuration, generated API types, a thin client, and CSS theme tokens.

Requirement Project records MUST live under the root docs/ directory.

Rationale Placing them inside the LiteSpec submodule or the application tree makes them disappear when either is replaced.

Requirement A README under docs/ MUST link to the approved record rather than restate its content.

Rationale A README that restates a decision becomes a second authored source that drifts from the record it summarizes.