Project structure

This guide is a map of the repository. After reading it, you will know which folder to open for a given change, where the written rules are, and which commands check your work.

One repository, several packages#

Neatship is a monorepo: one git repository that holds several packages. Nx (the task runner) runs tasks such as lint or test for each package, and caches the results so unchanged packages are not checked twice. Yarn 4 installs the libraries for all packages at once.

The tag, set in each package's project.json, decides what a package may import. The app/enforce-module-boundaries lint rule enforces it:

• the web app and the landing page may import app-ui, app-shared and front-end packages, never the server;
• the server may import app-shared, never the web app or app-ui;
• app-shared and app-ui import only shared packages.

Inside the server#

packages/app-server/
  src/
    main.ts                 the HTTP server entry point
    queue-worker/           the background worker entry point (no HTTP)
    app.module.ts           the root module
    engine/                 the platform: reused by every feature
      core-modules/         auth, billing, webhook, message-queue, app-config, logger,
                            secret-encryption, i18n, user, workspace, health...
      api/graphql/          GraphQL errors, the error handler, schema generation
      guards/               authentication and permission guards
      decorators/           @AuthUser(), @AuthWorkspace(), validation helpers
      middlewares/          request ids, and the middleware that signs each request in
      workspace-scoped-repository/   data access limited to one workspace
    modules/                your product features (Projects is the example)
    database/
      typeorm/core/migrations/       the database migrations
      seeds/                the sample data
      scripts/              seed and reset scripts
    utils/custom-exception.ts
  test/integration/         API tests against a real database
  generated/schema.graphql  the GraphQL schema, generated and committed

The rule of direction: modules/ may use engine/, never the reverse.

Inside the web app#

packages/app-front/src/
  modules/<feature>/        one folder per feature
    components/             one component per file
    effect-components/      components that render nothing and only run side effects
    hooks/                  useSomething.ts
    graphql/                fragments/, queries/, mutations/ (one operation per file)
    states/                 screen state (Jotai atoms)
    utils/  types/  constants/
    __tests__/
  pages/<area>/             thin route screens that assemble module components
  generated/graphql.ts      TypeScript types generated from the GraphQL schema
  locales/                  translation catalogs
  testing/                  test helpers and mock data

Two import shortcuts replace relative paths: @/ points to src/modules/ and ~/ points to src/. Relative imports that go up a folder (../) are a lint error.

The rulebook#

The written rules live in two places. Both are meant for people and for AI assistants.

• CLAUDE.md at the root: the short list of house rules, the local development commands and the known pitfalls ("Gotchas"). AGENTS.md is a link to the same file, for assistants that read that name.
• docs/conventions/: the full rules, one file per area.

Some sections of docs/conventions/ describe how to build pieces the starter doesn't include because none of its features needs them (for example a cache, feature flags, file uploads, emails, or a captcha on your own forms). They are marked Not included; none is needed to run in production, and each section says how to add the piece when your product needs it. Storybook covers the design system only: the web app has none (not included). When a rule and the code disagree, the code in the folder you are editing wins, as CLAUDE.md says: "the adjacent files in the directory you are editing beat any written rule".

Naming at a glance#

A few more house rules: type instead of interface; string unions instead of enum (except GraphQL enums); never any; named exports only; no abbreviations; short // comments that explain why, never what. Before writing a helper, look in app-shared/utils (isDefined, assertUnreachable, parseJson, findOrThrow...): rewriting an existing helper is the most common mistake in AI-written code.

How the checks run#

Replace <package> with a package name: app-front, app-server, app-shared, app-ui, app-website or app-lint-rules.

Every TypeScript package uses strict mode and noUncheckedIndexedAccess (reading list[0] gives a value that may be undefined, so the code must handle it).

Some files are generated and committed. yarn verify rewrites the ones your change affects and lists them; CI regenerates them and fails when the committed copy differs:

The editor settings in .vscode/ format on save, fix lint problems on save and make automatic imports use the aliases. The custom lint rules don't run inside the editor: they run through nx lint, yarn verify, the Claude Code hook after each edit, and CI.

Next#

• Working with AI assistants
• Add a feature
• Testing