runlify 0.0.794 → 0.0.796

package/docs/06-storage.md

@@ -0,0 +1,129 @@
+# Storage
+
+> **Load this file when:** you need to choose or change the storage engine for an entity.
+>
+> Related: [03-entity-types.md#storage](./03-entity-types.md#storage) ·
+> [09-options.md](./09-options.md)
+
+---
+
+## StorageType values
+
+Import: `import { Storage, StorageType } from 'runlify'`
+
+| Constant | String value | What it means |
+|----------|-------------|---------------|
+| `Storage.POSTGRES` | `'postgres'` | PostgreSQL only. Default for all entities. |
+| `Storage.ELASTIC` | `'elastic'` | Elasticsearch only. No Prisma model generated. |
+| `Storage.CLICKHOUSE` | `'clickhouse'` | ClickHouse only. No Prisma model generated. |
+| `Storage.POSTGRES_WITH_ELASTIC_SEARCH` | `'postgres_with_elastic_search'` | PostgreSQL as primary store + Elasticsearch for search queries |
+| `Storage.POSTGRES_WITH_CLICKHOUSE_SEARCH` | `'postgres_with_clickhouse_search'` | PostgreSQL as primary store + ClickHouse for search queries |
+
+---
+
+## How to set storage
+
+```ts
+entity.setStorage(Storage.POSTGRES_WITH_ELASTIC_SEARCH)
+```
+
+The storage must be set **before** adding fields, because some storage types force
+the `id` type to `string`.
+
+---
+
+## Side effects of `setStorage()`
+
+| Storage | Forces `id` type | Creates external tracking entity | Notes |
+|---------|-----------------|----------------------------------|-------|
+| `POSTGRES` | No | No | Default |
+| `ELASTIC` | `string` (cuid) | No | No Prisma schema |
+| `CLICKHOUSE` | `string` (cuid) | No | No Prisma schema |
+| `POSTGRES_WITH_ELASTIC_SEARCH` | `string` (cuid) | Yes: `external<Entity>SearchTrackings` | Dual-write: PG + ES |
+| `POSTGRES_WITH_CLICKHOUSE_SEARCH` | `string` (cuid) | Yes: `external<Entity>SearchTrackings` | Dual-write: PG + CH |
+
+The `external<Entity>SearchTrackings` catalog is auto-generated and tracks sync state
+between Postgres and the external search engine.
+
+---
+
+## Infrastructure requirements
+
+Setting a non-Postgres storage triggers bootstrap generation:
+
+| Storage contains | Generated bootstrap |
+|-----------------|---------------------|
+| `elastic` or `postgres_with_elastic_search` | `generateBackElasticBootstrap` — ES client init, index creation jobs |
+| `clickhouse` or `postgres_with_clickhouse_search` | `generateBackClickHouseBootstrap` — CH client init, table creation jobs |
+
+These bootstraps require the corresponding config vars to be set:
+- Elasticsearch: `es.enabled`, `es.node` (or `es.cloudId` + `es.username` + `es.password`)
+- ClickHouse: `ch.enabled`, `ch.host`, `ch.port`, `ch.database`, `ch.username`, `ch.password`
+
+---
+
+## Choosing the right storage
+
+| Scenario | Recommended storage |
+|----------|---------------------|
+| Standard CRUD entity | `Storage.POSTGRES` |
+| Entity with full-text search needs, Postgres as source of truth | `Storage.POSTGRES_WITH_ELASTIC_SEARCH` |
+| Analytical / time-series data with heavy aggregation | `Storage.POSTGRES_WITH_CLICKHOUSE_SEARCH` or `Storage.CLICKHOUSE` |
+| Pure analytics table, no CRUD | `Storage.CLICKHOUSE` |
+| Pure search index, no relational data | `Storage.ELASTIC` |
+
+---
+
+## Helper functions (exported from `runlify`)
+
+```ts
+isStoragePostgres(storage)              // true for POSTGRES, PG+ES, PG+CH
+isStorageElasticOnly(storage)           // true only for ELASTIC
+isStorageClickHouseOnly(storage)        // true only for CLICKHOUSE
+isStorageExternalSearch(storage)        // true for PG+ES, PG+CH
+isStorageElasticSearch(storage)         // true for ELASTIC, PG+ES
+isStorageClickHouseSearch(storage)      // true for CLICKHOUSE, PG+CH
+getSearchEngine(storage)                // returns 'elastic' | 'clickhouse' | null
+usesPrismaDelegate(storage)             // false only for ELASTIC and CLICKHOUSE
+```
+
+---
+
+## Anti-patterns
+
+### Setting `id` type after setting external search storage
+
+**Wrong:**
+```ts
+entity.setStorage(Storage.POSTGRES_WITH_ELASTIC_SEARCH)
+entity.getKey().setType('int')   // silently overrides forced 'string' type
+```
+
+**Why:** `setStorage()` with external-search storage forces `id` to `string` (cuid).
+Overriding it to `int` or `bigint` breaks the external search sync because search engine
+IDs must be strings.
+
+**Correct:** do not override the key type when using external search storage.
+
+---
+
+### Using `ELASTIC` or `CLICKHOUSE` for entities that need relational joins
+
+**Wrong:**
+```ts
+const orders = system.addDocument('orders')
+orders.setStorage(Storage.ELASTIC)   // no Prisma model, no FK support
+orders.addLinkField('users', 'userId')   // FK has nowhere to land
+```
+
+**Why:** `ELASTIC` and `CLICKHOUSE` storages do not generate a Prisma model, so foreign
+keys and relational queries are not supported.
+
+**Correct:** use `POSTGRES_WITH_ELASTIC_SEARCH` to keep Postgres as the relational
+source of truth while gaining search capabilities.
+
+---
+
+> **Examples:** this file intentionally omits code examples. Add real usage examples
+> from the consuming project here. A reference metadata file is typically at
+> `src/meta/metadata.ts` in the meta project.

package/docs/07-backend-file-graph.md

@@ -0,0 +1,231 @@
+# Backend File Graph (`<prefix>-back`)
+
+> **Load this file when:** you need to find a specific file in the generated backend,
+> understand which files are safe to edit, or know what gets regenerated.
+>
+> Legend: `[gen]` = regenerated every `regen` (DO NOT EDIT) · `[yours]` = created once,
+> yours to implement · `[once]` = created once by Runlify, rarely needs changes
+>
+> Related: [01-overview.md](./01-overview.md) · [08-frontend-file-graph.md](./08-frontend-file-graph.md)
+
+---
+
+## Full tree
+
+```
+<prefix>-back/
+│
+├── src/
+│   │
+│   ├── config/
+│   │   └── config.ts                          [gen]  Runtime config loader (reads env JSON)
+│   │
+│   ├── adm/
+│   │   │
+│   │   ├── graph/
+│   │   │   ├── permissionsToGraphql.ts        [gen]  Permission → GraphQL mapping
+│   │   │   ├── additionalResolvers.ts         [gen]  Wires additional service resolvers
+│   │   │   ├── additionalTypes.ts             [gen]  Additional GraphQL type definitions
+│   │   │   │
+│   │   │   └── <EntityName>/                  [gen]  Per-entity GraphQL folder
+│   │   │       ├── resolvers.ts               [gen]  CRUD resolvers
+│   │   │       ├── types.ts                   [gen]  GraphQL type definitions
+│   │   │       └── permissionsToGraphql.ts    [gen]  Entity permission mappings
+│   │   │
+│   │   └── services/
+│   │       └── <EntityName>Service/           One folder per entity
+│   │           │
+│   │           ├── <EntityName>Service.ts     [gen]  Base service class — DO NOT EDIT
+│   │           ├── Additional<Entity>Service.ts [yours] Your custom methods + overrides
+│   │           ├── config.ts                  [gen]  Service configuration
+│   │           ├── initBuiltInHooks.ts        [gen]  Wires built-in framework hooks
+│   │           ├── initUserHooks.ts           [yours] Wire your custom hooks here
+│   │           │
+│   │           └── hooks/
+│   │               ├── beforeCreate.ts        [yours] Runs before INSERT
+│   │               ├── afterCreate.ts         [yours] Runs after INSERT
+│   │               ├── beforeUpdate.ts        [yours] Runs before UPDATE
+│   │               ├── afterUpdate.ts         [yours] Runs after UPDATE
+│   │               ├── beforeDelete.ts        [yours] Runs before DELETE
+│   │               ├── afterDelete.ts         [yours] Runs after DELETE
+│   │               ├── beforeUpsert.ts        [yours] Runs before UPSERT
+│   │               ├── additionalOperationsOnCreate.ts  [yours] Side-effects after create
+│   │               ├── additionalOperationsOnUpdate.ts  [yours] Side-effects after update
+│   │               ├── additionalOperationsOnDelete.ts  [yours] Side-effects after delete
+│   │               ├── changeListFilter.ts    [yours] Mutate the list query filter at runtime
+│   │               └── tenantIdRequiredHooks.ts [yours] Tenant isolation (only if multitenancy enabled)
+│   │
+│   ├── clients/
+│   │   ├── createPgPrismaClient.ts            [gen]  Prisma client factory
+│   │   └── getPrisma.ts                       [gen]  Prisma client getter (per DB)
+│   │
+│   ├── rest/
+│   │   └── restRouter.ts                      [once] Custom REST endpoints (yours)
+│   │
+│   ├── init/
+│   │   └── roles/
+│   │       ├── generated/
+│   │       │   ├── initPermissions.ts         [gen]  Collects and seeds all permissions
+│   │       │   └── uiPermissions.ts           [gen]  'ui.<entity>.list' per entity + system pages
+│   │       ├── customPermissions.ts           [once] Your hand-written data-space permissions
+│   │       └── customUiPermissions.ts         [once] Your hand-written UI-space permissions
+│   │
+│   ├── enums/
+│   │   ├── enums.ts                           [gen]  All entity name enums
+│   │   ├── devEnums.ts                        [gen]  Dev-only enums
+│   │   └── initEntities.ts                    [gen]  Entity registry initialisation
+│   │
+│   └── index.ts                               [gen]  Application entry point
+│
+├── prisma/
+│   └── schema.<dbName>.prisma                 [gen]  Prisma schema (one per database)
+│
+├── config/
+│   ├── dev.json                               [gen]  Dev environment config (values from meta)
+│   └── prod.json                              [gen]  Prod environment config (values from meta)
+│
+├── docs/
+│   ├── spec.md                                [gen]  Auto-generated project specification
+│   ├── configuration.md                       [gen]  Config vars documentation
+│   └── entities/
+│       └── <EntityName>.md                    [gen]  Per-entity documentation
+│
+├── Dockerfile                                 [gen]  Backend Docker image
+├── .gitlab-ci.yml                             [gen]  GitLab CI pipeline
+│
+└── chart/                                     Helm chart for Kubernetes
+    ├── Chart.yaml                             [gen]
+    ├── values.yaml                            [gen]
+    └── templates/
+        ├── back.yaml                          [gen]  Deployment manifest
+        └── ingress.yaml                       [gen]  Ingress manifest
+```
+
+---
+
+## Per-entity service: what to edit and what not to
+
+### `<EntityName>Service.ts` — DO NOT EDIT {#entity-service-generated}
+
+Generated on every `regen`. Contains:
+- Standard CRUD operations (`getAll`, `getById`, `create`, `update`, `delete`)
+- Prisma query building, filter application, sorting, pagination
+- Hook invocation calls (calls into `initUserHooks.ts`)
+
+### `Additional<EntityName>Service.ts` — yours {#additional-service}
+
+Created once. Never overwritten. This is where you add:
+- Custom methods that are too complex for the standard service
+- Business logic that wraps or extends generated CRUD
+- Helper methods used by hooks
+
+### `hooks/` — yours {#hooks}
+
+All hook files are created once and never overwritten.
+
+| Hook file | When called | Common uses |
+|-----------|------------|-------------|
+| `beforeCreate.ts` | Before DB INSERT | Validate, enrich input, set computed fields |
+| `afterCreate.ts` | After DB INSERT | Send notifications, trigger side effects |
+| `beforeUpdate.ts` | Before DB UPDATE | Validate new state, check transitions |
+| `afterUpdate.ts` | After DB UPDATE | Sync caches, publish events |
+| `beforeDelete.ts` | Before DB DELETE | Check dependencies, soft-delete fallback |
+| `afterDelete.ts` | After DB DELETE | Clean up related data |
+| `beforeUpsert.ts` | Before UPSERT | |
+| `additionalOperationsOnCreate.ts` | After create, separate tx context | Audit log, async tasks |
+| `additionalOperationsOnUpdate.ts` | After update, separate tx context | |
+| `additionalOperationsOnDelete.ts` | After delete, separate tx context | |
+| `changeListFilter.ts` | On every list query | Inject runtime filters (tenant, user scope) |
+| `tenantIdRequiredHooks.ts` | On create (multitenancy only) | Ensure `tenantId` is set from user context |
+
+### `initUserHooks.ts` — yours {#init-user-hooks}
+
+Registers your hook implementations with the framework. Created once.
+When you implement a hook, register it here.
+
+### `initBuiltInHooks.ts` — DO NOT EDIT {#init-built-in-hooks}
+
+Generated. Registers framework-level hooks (audit logging, search index sync, etc.).
+
+---
+
+## Prisma schema
+
+One `.prisma` file per registered database:
+- `schema.main.prisma` — always generated
+- `schema.<name>.prisma` — generated for each additional database registered via
+  `system.addDatabase(name)`
+
+The schema is fully generated. **Do not edit it** — all model definitions come from
+the meta. Schema changes go in the meta, not in the `.prisma` file.
+
+**Anti-pattern — editing the Prisma schema directly:**
+
+```
+// WRONG: you add a column directly to schema.main.prisma
+model Order {
+  id     Int    @id @default(autoincrement())
+  myField String  // <-- added manually
+}
+```
+
+After the next `regen`, `myField` is gone.
+
+**Correct:** add the field in `metadata.ts` via `entity.addField('myField')`, then regen.
+
+---
+
+## Config files (`config/`)
+
+`dev.json` and `prod.json` are generated from the config vars defined in `metadata.ts`.
+They contain placeholder / default values.
+
+**Do not commit secrets** to these files. They are intended as value templates.
+Actual secret values should be injected from CI/CD environment variables, not from these
+files.
+
+---
+
+## Permissions (`init/roles/`)
+
+`permissionsToGraphql.ts` and its per-entity counterparts map permission strings to
+GraphQL methods. How permissions are named, structured, and seeded into the database
+(`init/roles/initPermissions.ts` and friends) is covered in full in
+[11-permissions.md](./11-permissions.md).
+
+---
+
+## Anti-patterns
+
+### Adding custom logic to `<EntityName>Service.ts`
+
+**Wrong:** editing the generated service file directly.
+
+**Why:** overwritten on every `regen`. Your changes are lost.
+
+**Correct:** use `Additional<EntityName>Service.ts` for custom logic or `hooks/` for
+lifecycle interception.
+
+---
+
+### Creating custom hooks outside the `hooks/` directory
+
+**Wrong:** adding a `customHook.ts` file inside `<EntityName>Service/` and calling it
+directly from `Additional<EntityName>Service.ts`.
+
+**Why:** works, but bypasses the hook registration system. Framework hooks (audit,
+search) won't compose correctly with custom hooks unless they go through `initUserHooks`.
+
+**Correct:** implement hooks in the designated `hooks/` files and register them in
+`initUserHooks.ts`.
+
+---
+
+### Modifying `initBuiltInHooks.ts`
+
+**Wrong:** editing the generated file to remove audit logging or search sync hooks.
+
+**Why:** the file is regenerated. Your changes are lost.
+
+**Correct:** if you need to suppress a built-in hook, do it via the meta (e.g.
+`entity.setAuditable(false)` to disable audit logging).

package/docs/08-frontend-file-graph.md

@@ -0,0 +1,260 @@
+# Frontend File Graph (`<prefix>-ui`)
+
+> **Load this file when:** you need to find a specific file in the generated frontend,
+> understand which files are safe to edit, or know what gets regenerated.
+>
+> Legend: `[gen]` = regenerated every `regen` (DO NOT EDIT) · `[yours]` = created once,
+> yours to implement · `[once]` = created once, rarely needs changes
+>
+> Related: [01-overview.md](./01-overview.md) · [07-backend-file-graph.md](./07-backend-file-graph.md) ·
+> [11-permissions.md](./11-permissions.md)
+
+---
+
+## Full tree
+
+```
+<prefix>-ui/
+│
+└── src/
+    │
+    ├── adm/
+    │   │
+    │   ├── pages/
+    │   │   └── <EntityName>/               One folder per entity
+    │   │       │
+    │   │       ├── <EntityName>List/
+    │   │       │   ├── index.tsx           [gen]  Entry point — re-exports Default or custom
+    │   │       │   ├── Default<Entity>List.tsx  [gen]  Generated list component
+    │   │       │   ├── <Entity>Filter.tsx  [yours] Your custom filter (created once)
+    │   │       │   ├── Default<Entity>Filter.tsx [gen]  Generated default filter
+    │   │       │   └── <Entity>ListBreadcrumbs.tsx [gen]  Breadcrumb component
+    │   │       │
+    │   │       ├── <EntityName>Show/
+    │   │       │   ├── index.tsx           [gen]  Entry point
+    │   │       │   ├── Default<Entity>Show.tsx  [gen]  Generated show component
+    │   │       │   ├── MainTab.tsx         [yours] Your custom main tab content
+    │   │       │   ├── DefaultMainTab.tsx  [gen]  Generated main tab
+    │   │       │   ├── DefaultActions.tsx  [gen]  Generated action buttons
+    │   │       │   ├── additionalTabs.tsx  [yours] Your extra tabs in show view
+    │   │       │   └── tabs/
+    │   │       │       └── <RelatedEntity>Tab.tsx  [gen]  Auto-generated dependency tabs
+    │   │       │
+    │   │       ├── <EntityName>Create/
+    │   │       │   ├── index.tsx           [gen]  Entry point
+    │   │       │   └── Default<Entity>Create.tsx [gen]  Generated create form
+    │   │       │
+    │   │       └── <EntityName>Edit/
+    │   │           ├── index.tsx           [gen]  Entry point
+    │   │           └── Default<Entity>Edit.tsx   [gen]  Generated edit form
+    │   │
+    │   ├── widgets/
+    │   │   └── <EntityName>/
+    │   │       ├── <Entity>CountWidget.tsx [gen]  Count widget for dashboard
+    │   │       └── <Entity>ListWidget.tsx  [gen]  List widget for dashboard
+    │   │
+    │   ├── resources.tsx                   [gen]  react-admin resource registry
+    │   ├── resourcesChunk0.tsx             [gen]  Chunked resource imports (code splitting)
+    │   ├── resourcesChunk1.tsx             [gen]  Chunked resource imports
+    │   ├── ResourcesPage.tsx               [gen]  /resources debug page
+    │   ├── MetaPage.tsx                    [gen]  /meta debug page
+    │   ├── entityMapping.ts                [gen]  Entity name → component mapping
+    │   ├── routes.tsx                      [gen]  All react-admin routes
+    │   ├── additionalRoutes.tsx            [yours] Your custom routes/pages
+    │   ├── Dashboard.tsx                   [yours] Home page content
+    │   ├── PermissionPage.tsx              [once]  Shown when withPermission denies access
+    │   ├── NotFoundPage.tsx                [once]  Shown when an action doesn't exist on the entity
+    │   ├── getDefaultMenu.ts               [gen]  Auto-generated sidebar menu
+    │   ├── getAdditionalMenu.ts            [yours] Your extra menu items
+    │   │
+    │   └── functions/
+    │       └── Functions.tsx               [gen]  System functions page
+    │
+    ├── i18n/
+    │   ├── types.ts                        [once]  ValidationMessages type (one per project)
+    │   └── <lang>/
+    │       ├── <lang>Catalogs.ts           [gen]   Catalog translations for this language
+    │       ├── <lang>Docs.ts               [gen]   Document translations (exports `<lang>Documents`)
+    │       ├── <lang>InfoRegistries.ts     [gen]
+    │       ├── <lang>SumRegistries.ts      [gen]
+    │       ├── <lang>Reports.ts            [gen]
+    │       ├── <lang>Validation.ts         [once]  Validation messages (one per language)
+    │       └── index.ts                    [once]  Assembles the above + custom keys, per language
+    │
+    ├── utils/
+    │   └── permissions.ts                  [gen]   hasPermission / hasAnyPermission / hasAllPermissions / withPermission
+    │
+    └── environment/
+        ├── src/
+        │   ├── App.tsx                    [gen]  Root react-admin App component
+        │   ├── dataProvider/
+        │   │   ├── index.ts               [gen]  GraphQL data provider
+        │   │   └── getAdditionalMethods.ts [once] Hook for custom data provider methods
+        │   ├── i18nProvider/
+        │   │   └── index.ts               [gen]  react-admin i18n provider — merges src/i18n/<lang> per language
+        │   ├── layout/
+        │   │   ├── AppBar.tsx             [gen]  Top application bar
+        │   │   └── Menu.tsx               [gen]  Sidebar menu component
+        │   ├── routes.ts                  [gen]  Route registration
+        │   └── contexts/
+        │       └── SpacesContext.ts       [gen]  Multi-space / tenant context
+        │
+        ├── .gitlab-ci.yml                 [gen]  GitLab CI pipeline for UI
+        ├── Dockerfile                     [gen]  nginx-based frontend Docker image
+        └── chart/                         Helm chart for Kubernetes
+            ├── Chart.yaml                 [gen]
+            ├── values.yaml                [gen]
+            └── templates/
+                ├── front.yaml             [gen]
+                └── ingress.yaml           [gen]
+```
+
+---
+
+## Per-entity: what to edit and what not to
+
+### List page
+
+| File | Owner | When to edit |
+|------|-------|-------------|
+| `index.tsx` | `[gen]` | Never — re-exports Default or your override |
+| `Default<Entity>List.tsx` | `[gen]` | Never |
+| `Default<Entity>Filter.tsx` | `[gen]` | Never |
+| `<Entity>Filter.tsx` | `[yours]` | Customise filter fields, add new filters |
+| `<Entity>ListBreadcrumbs.tsx` | `[gen]` | Never |
+
+### Show page
+
+| File | Owner | When to edit |
+|------|-------|-------------|
+| `index.tsx` | `[gen]` | Never |
+| `Default<Entity>Show.tsx` | `[gen]` | Never |
+| `DefaultMainTab.tsx` | `[gen]` | Never |
+| `MainTab.tsx` | `[yours]` | Override the main tab layout |
+| `DefaultActions.tsx` | `[gen]` | Never |
+| `additionalTabs.tsx` | `[yours]` | Add extra tabs to the show view |
+| `tabs/<Related>Tab.tsx` | `[gen]` | Never — auto-generated dependency lists |
+
+### Create / Edit pages
+
+All files under `Create/` and `Edit/` are `[gen]`. Form fields and their order are
+controlled from the meta via `entity.getForms()`. See [03-entity-types.md](./03-entity-types.md).
+
+---
+
+## System-level files
+
+### `Dashboard.tsx` — yours {#dashboard}
+
+The home page of the admin UI. Empty by default. Add widgets, stats, charts here.
+Widget components are generated per-entity in `widgets/<EntityName>/`.
+
+### `additionalRoutes.tsx` — yours {#additional-routes}
+
+Register custom react-admin `<Route>` components here. Used for non-entity pages like
+reports, custom dashboards, or wizard flows.
+
+### `getAdditionalMenu.ts` — yours {#additional-menu}
+
+Return extra menu items from this function. Appended to the auto-generated menu.
+Menu items added via `system.addGroupMenuItem` / `addInternalMenuItem` etc. in the meta
+are reflected in `getDefaultMenu.ts` — do not edit that file.
+
+### `PermissionPage.tsx` / `NotFoundPage.tsx` — once {#permission-fallbacks}
+
+Fallback components rendered instead of a page's real content. Both re-export a
+react-admin built-in by default and are safe to replace. See
+[11-permissions.md](./11-permissions.md#fallback-components) for when each one is used.
+
+---
+
+## How the menu is built
+
+```
+getDefaultMenu.ts  [gen]   ← from system.addGroupMenuItem / addInternalMenuItem in meta
+getAdditionalMenu.ts [yours] ← your custom extra items
+
+Menu.tsx [gen]             ← combines both
+```
+
+**Anti-pattern — editing `getDefaultMenu.ts` to add menu items:**
+
+```ts
+// WRONG: overwritten on next regen
+export const getDefaultMenu = () => [
+  ...generatedItems,
+  { label: 'My Custom Page', path: '/custom' }  // lost on regen
+]
+```
+
+**Correct:** add menu items in `getAdditionalMenu.ts` (for frontend-only custom items)
+or via `system.addInternalMenuItem` / `addGroupMenuItem` in the meta (for items
+backed by a page registered in the system).
+
+---
+
+## i18n {#i18n}
+
+Entity/field-derived translation files (`<lang>Catalogs.ts`, `<lang>Docs.ts`,
+`<lang>InfoRegistries.ts`, `<lang>SumRegistries.ts`, `<lang>Reports.ts`) are `[gen]` —
+fully generated from entity titles and field titles defined in the meta. To change one
+of these translations:
+
+1. Update the title in `metadata.ts`: `entity.setTitle({ singular: 'Order', plural: 'Orders' }, 'en')`
+2. Run `regen`
+
+Three other files exist per project/language and are `[once]` — created only if
+missing, then yours to edit freely:
+
+| File | Scope | Purpose |
+|------|-------|---------|
+| `i18n/types.ts` | One per project | The `ValidationMessages` type — add fields here as you add validation messages |
+| `i18n/<lang>/<lang>Validation.ts` | One per language | Validation message strings, typed by `ValidationMessages` |
+| `i18n/<lang>/index.ts` | One per language | Assembles all of the above into the object `i18nProvider` imports; the place to add any translation key that isn't derived from an entity/field (UI labels, error messages, etc.) |
+
+`i18n/<lang>/index.ts` is what `environment/src/i18nProvider/index.ts` (`[gen]`)
+actually imports — it merges the entity-derived generated files, `<lang>Validation.ts`,
+and falls back to `ra-language-english` for anything not overridden. Since it's created
+once, it's safe to add project-specific keys directly into it.
+
+**Anti-pattern — editing an entity/field-derived translation file directly:**
+
+Editing `<lang>Catalogs.ts`, `<lang>Docs.ts`, or any other `[gen]` lang file is
+pointless — changes are overwritten on regen. Add custom keys to `i18n/<lang>/index.ts`
+instead.
+
+---
+
+## Data provider
+
+`dataProvider/index.ts` is generated. It wires the react-admin data provider to the
+GraphQL backend.
+
+`dataProvider/getAdditionalMethods.ts` is created once. Use it to add custom data
+provider methods for non-standard GraphQL queries.
+
+---
+
+## Anti-patterns
+
+### Editing `Default<Entity>*.tsx` components
+
+**Wrong:** modifying generated list/show/create/edit components directly.
+
+**Why:** overwritten on every `regen`. Your changes vanish.
+
+**Correct:**
+- For list: customise `<Entity>Filter.tsx`
+- For show: implement `MainTab.tsx` or add tabs in `additionalTabs.tsx`
+- For create/edit: adjust field visibility/order in the meta via `entity.getForms()`
+  or `field.setShowInCreate(false)` / `setShowInEdit(false)`
+
+---
+
+### Adding custom routes directly to `routes.tsx`
+
+**Wrong:** editing the generated `routes.tsx` to add a new route.
+
+**Why:** overwritten on regen.
+
+**Correct:** add custom routes in `additionalRoutes.tsx`.