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 TypeScript monorepo: npm workspaces, no custom tooling:

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; 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.*) instead of hand-written utility classes, so recoloring and rebranding stay a one-file change.

The conventions file

AGENTS.md at the project root is the style guide: bonds, handler patterns, migration discipline, i18n, testing. It is written for AI agents, and it is the shortest human summary of how the project expects to grow. 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; do not let the two drift.