Project structure

Anatomy of a molecule project: the api/ and app/ workspaces, migrations, i18n, ClassMap styling, and the AGENTS.md conventions file.

The shape

Every scaffold is a conventional, fully-owned TypeScript monorepo — no framework magic, just npm workspaces:

my-app/
├── api/                  # Express server
│   ├── src/              #   routes, handlers, bonds.ts, ai/
│   ├── migrations/       #   ordered SQL migrations + migrate.ts
│   └── .env.example      #   every secret the api expects
├── app/                  # React + Vite client
│   ├── src/              #   screens, components, locales/
│   ├── e2e/              #   Playwright specs that already run
│   └── .env.example
├── AGENTS.md             # the project’s conventions, for any AI agent
└── package.json          # npm workspaces: api + app

The API

Express, with one router file per resource and handlers that read and write through the bonds. Database schema changes always ship as a migration — npx mlcl db migrate applies them (see Databases).

The app

React + Vite. Screens compose the shared UI framework; all user-facing text goes through i18n (t('key', values, { defaultValue }), translations in src/locales/), and styling goes through the class map (getClassMap() → cm.*), never hand-written utility soup — that is what keeps recoloring and rebranding a one-file change.

The conventions file

AGENTS.md at the project root is the authoritative style guide — bonds, handler patterns, migration discipline, i18n, testing. It is written for AI agents but it is the fastest human summary of how the project expects to grow. npx mlcl agent init writes or refreshes it.

Note

When a generated app seems to break a rule, the rule wins: fix the code to match AGENTS.md, or change AGENTS.md deliberately — don’t let the two drift.