templates.AdminDashboard/SPEC.md

Admin Dashboard / CRM — product specification

This is the contract the project is built against. It is written for the agent that scaffolds the repository, but it doubles as the human-readable brief: every requirement below is meant to be implementable and verifiable.

Values in angle brackets (<App name>, <entities>, <auth provider>) come from the project-creation dialog and are recorded in the project record; replace them as you read.

1. Goal

An internal back-office / CRM that an operations team could actually run on day one: sign in with the configured <auth provider>, see a dashboard of KPIs, manage the supplied <entities> through generated data tables and record forms, search across everything, import and export CSV, and trust an append-only audit trail for every change. The CRUD surface is generic and driven by entity metadata — one registry defines the entities and their typed fields, and the list views, forms, filters and related-record links are generated from it, so adding a field is a metadata change, not new hand-written screens for every entity.

It must be runnable end-to-end on day one (with seeded demo data and a seeded admin), not a set of screens wired together later.

Non-goals (do not build unless the must-have list says otherwise): a public/customer-facing portal, marketing pages, billing/subscriptions, real-time collaboration, workflow automation/approvals, ML scoring, mobile apps.

2. Roles

Role	Can do
Viewer	Sign in, view the dashboard, browse and search any entity they can read, open records, run exports. Read-only.
Editor	Everything a viewer can, plus create, update, soft-delete and restore records in the entities they are granted.
Admin	Everything an editor can, plus manage entity metadata and field definitions, manage roles/permissions, delete permanently, and read the full audit trail.

RBAC is per entity and per action: a role maps to { entity, actions[] } where actions are read | create | update | delete | restore | export | import. A user may hold different rights on different entities (e.g. edit customers, read-only deals). Authentication is <auth provider>; provide a seeded admin account for local development so a reviewer can log in immediately.

3. Information architecture (routes)

Auth:

• /login — sign in (and the SSO callback route when <auth provider> is SSO / OIDC).
• /logout.

App (guarded; the entity routes are generated from the registry):

• / — dashboard: KPI cards, recent activity, quick links to each entity.
• /search — global search across the readable entities.
• /:entity — generic list view for one entity: server-side pagination, sorting, filters.
• /:entity/new — generic record form (create).
• /:entity/:id — record detail: field values, related-record links, change history.
• /:entity/:id/edit — generic record form (edit); destructive actions live here behind confirmation.
• /import — CSV import: upload, column mapping, dry-run preview, commit, per-row errors.
• /audit — audit trail: filter by actor, entity, action and date; immutable entries.
• /settings/entities — entity & field metadata registry (admin only).
• /settings/roles — roles and per-entity permission matrix (admin only).
• /settings/saved-views — saved list filters (personal and shared).

Access to /:entity routes is denied (403) when the signed-in role has no read on that entity; the nav only shows entities the role can read.

4. Data model

Minimum viable entities (add fields the requirements imply; keep them typed and validated):

• EntityDefinition — id, key (route segment), label, labelPlural, icon, isSystem, displayField, sortField, defaultSortDirection, createdAt.
• FieldDefinition — id, entityId, key, label, type (text | textarea | number | date | boolean | select | relation), isRequired, isUnique, options[], relationEntityId?, isListColumn, listOrder, isFilterable, isSortable, defaultValue, validationRules (min/max/ pattern/maxLength). The pair EntityDefinition + FieldDefinition is the typed registry that drives the generated tables and forms.
• Domain entities — the user-supplied <entities> (e.g. customers, deals, activities, tasks). Each is a real, typed table/collection whose columns follow its FieldDefinitions; it carries the shared audit columns below. Model them with migrations, not a schemaless blob, and seed a few rows each so lists are presentable on first run.
• Shared record columns — id, createdAt, createdBy, updatedAt, updatedBy, deletedAt? (soft delete), deletedBy?. deletedAt IS NULL means active.
• Role — id, key (viewer | editor | admin or custom), name, isSystem.
• Permission — id, roleId, entityId (or *), actions[] (read/create/update/delete/ restore/export/import).
• User — id, email, name, passwordHash?, externalId? (for SSO), roleIds[], status, createdAt.
• AuditEvent — id, actorId, actorEmail, entityId, recordId, action (create | update | delete | restore | import), changes (before/after diff of changed fields), occurredAt. Append-only; never updated or deleted.
• SavedView — id, ownerId or shared flag, entityId, name, filters, sort, visibleColumns[].
• ImportJob — id, entityId, filename, status (pending | validating | ready | committed | failed), columnMapping, rowsTotal, rowsValid, rowsFailed, errors[], createdBy, createdAt. Export jobs may reuse it or stream directly without persisting a row.

Keep every field typed and validated; a record value that does not satisfy its FieldDefinition is a 422, not a stored string.

5. Key flows

1. Sign in → dashboard. A reviewer logs in with the seeded admin, lands on /, and sees KPI cards (record counts per entity, recent creates/updates, and at least one invented business KPI per seeded entity) plus recent audit activity.
2. Browse a list. The user opens /:entity, sees a server-paginated table of the visible columns, sorts by a sortable column, applies a filter and saves it as a saved view; reloading or sharing the filtered URL reproduces the same view.
3. Create / edit a record. The user opens the generated record form, fills typed fields, gets inline validation errors on submit, saves, and is taken to the record — which now appears in the list and has a new create/update entry in its change history.
4. Related records. From a record with a relation field the user follows a link to the related record; the reverse record lists its referrers.
5. Soft delete → restore. An editor soft-deletes a record: it disappears from the default list, the deletion is audited, and the record is recoverable from the "deleted" filter or the record view. An admin can restore it; permanent delete is admin-only, confirmed, and audited.
6. Audit. An admin opens /audit, filters to one record, and sees who changed what and when — including before/after values for each changed field — for every create, update, delete and restore.
7. Import / export. A user exports the current filtered list to CSV (streamed) and imports a CSV of new records: mapping columns to fields, seeing a dry-run with per-row errors, then committing only the valid rows — each committed row producing an audit event.
8. Admin metadata. An admin adds a field in /settings/entities, and it appears as a list column and form input for that entity without writing per-entity screen code.

6. Functional requirements

• Generic CRUD from metadata: list views, filters and forms are generated from EntityDefinition/FieldDefinition. No per-entity hand-written tables or forms.
• List views: server-side pagination (bounded page size), sorting, and filters derived from the filterable fields; empty state when a filter matches nothing; total count shown.
• Filters: text contains/equals, number/date ranges, select/boolean equals, and a relation picker; all applied server-side, never by loading the whole table.
• Record forms: one generated form per entity with typed inputs, required/unique/format validation, and inline, field-level errors returned by the server.
• Related records: relation fields render as links to the related record; the related record shows a back-reference list.
• Bulk actions: select rows and apply a bulk action (bulk soft-delete, bulk export, bulk field update where enabled) — each row audited, with a confirmation step.
• Dashboard: KPI cards and recent activity; numbers come from real (seeded) data, not placeholders.
• Global search: one query box that searches across the readable entities and returns grouped, paged results, respecting RBAC.
• CSV import/export: export streams the current filtered/selected set; import supports column mapping, a dry-run preview, per-row errors and a commit of valid rows only.
• Audit trail: every create/update/delete/restore writes an immutable AuditEvent with actor, timestamp and the changed fields; the record view and /audit expose them.
• Soft delete + restore: deletes set deletedAt; restore clears it; both are authorized and audited. Permanent delete is admin-only and confirmed.
• Saved views: persist filters/sort/columns per user and optionally shared.
• Admin: manage entity/field metadata and the role→permission matrix; no destructive action without confirmation.
• Seed data: a seeded admin (viewer + editor + admin usable immediately), the supplied entities with a few rows each, and a saved view or two, so the dashboard is presentable on first run.

7. Non-functional requirements

• Authorization: enforce every entity+action permission server-side per request — never only in the UI; a direct API call with insufficient rights must fail, not merely hide a button.
• Bounded queries: every list query is paginated and bounded with a server-enforced maximum page size; no unbounded scans of a table, ever (list, export and search included).
• Audit atomicity: the audit write is committed atomically with the mutation it records — in the same transaction. A change without an audit event, or an audit event without the change, must not be observable.
• Output escaping: escape every value rendered in the UI (field values, names, error text) so a stored string can never execute as markup.
• Streaming exports: large CSV exports stream to the client; they must not buffer the whole result set in memory. Imports validate in bounded batches.
• Destructive actions: require explicit confirmation and are recoverable wherever soft delete applies; permanent delete is admin-only.
• Resilience: every screen has explicit loading, empty and error states; validation errors are shown per field, not as one generic message.
• Observability: structured logs for imports, exports, permission denials and auth failures; a health endpoint.

8. Acceptance criteria (definition of done)

• Install, dev server, lint, typecheck, tests and production build all pass.
• A seeded admin can log in immediately and sees a dashboard with real (seeded) KPIs.
• Every supplied <entity> has a working list view and record form generating from metadata — CRUD works end-to-end with typed fields and server-returned validation errors.
• RBAC is enforced server-side per entity and action: viewer is read-only, editor can mutate its entities, admin manages metadata/roles, and a denied direct API call returns 403.
• Filters, sorting and pagination are applied server-side (LIMIT/OFFSET, not client slicing) and every list query is bounded.
• Every create, update, delete and restore writes an immutable audit record with actor, timestamp and changed fields, committed atomically with the mutation.
• Soft delete hides a record and restore brings it back; both are audited; permanent delete is admin-only and confirmed.
• Global search and CSV export respect RBAC; export streams and import supports mapping + dry-run with per-row errors.
• .env.example documents every secret; README quickstart (install, run, test, env) is accurate.
• CI runs install + lint + typecheck + tests + build.

9. Suggested build order

Follow this order and finish (and verify) a layer before starting the next:

1. Scaffold the chosen stack (with <database>), install dependencies, get the dev server and the empty shell running, and commit the skeleton.
2. Auth & roles — sign in with <auth provider>, the role→permission model, server-side enforcement, and the seeded admin.
3. Entity metadata + generic table — the EntityDefinition/FieldDefinition registry, migrations for the supplied <entities> and their seed rows, and the generated, server-paginated list view.
4. Generic record form — typed inputs, validation, relation links, bulk actions.
5. Audit trail — atomic audit writes for every mutation, the record change history and /audit.
6. Dashboard + global search — KPI cards, recent activity, cross-entity search.
7. Import / export — streaming CSV export, import with mapping, dry-run and per-row errors.
8. Quality — tests for the flows above, CI, README, .env.example, accessibility pass.