templates.AdminDashboard/README.md

Admin Dashboard / CRM — W4C project template

A W4C project template. Creating a project from it generates a private copy of this repository in your namespace and starts the Startup Creator agent, which drives the build from this brief.

This repository is deliberately a brief, not a finished app: it ships the product specification, the project metadata and the seed assets; the tech stack chosen in the creation dialog decides the scaffold. Read SPEC.md for the full product contract — roles, routes, data model, flows, functional and non-functional requirements, and the acceptance criteria the work is checked against.

What ships in this repository

Path	Purpose
README.md	This file: how the template is wired and how to work in the project.
SPEC.md	The product specification and acceptance criteria — the contract to build.
.gitignore	Default ignores for dependencies, build output, local secrets and editor/OS cruft.
.editorconfig	Shared editor defaults (UTF-8, LF, indentation) for the generated project.
.w4c/template.json	Template manifest: dialog fields, starter prompt, element list (templates only).
.w4c/project.json	Project metadata committed with the repository.
.w4c/diagrams/	Excalidraw architecture diagram.
.w4c/boards/roadmap.json	Board columns and the seed tasks for the build.
.w4c/workflows/	The CI workflow (ci-build.yaml + ci-build.sh) to import into the workflows module.

See .w4c/README.md for the full .w4c/ contract.

Stack

The creation dialog records the chosen stack (and its skill pair stack-* + stack-*-quality), the database and the auth provider. Scaffold with those skills and hold the work to their conventions and quality gates. The stack is not fixed here on purpose: the same brief is built on React + Vite, Next.js, Vue 3 + Quasar, Laravel + Vue, Phoenix, … without changing SPEC.md.

Build order

Work top-down, one layer at a time, and verify each layer before starting the next:

1. Scaffold the stack and get the empty shell running (install → dev server → commit).
2. Auth & roles — the role→permission model, server-side enforcement and the seeded admin.
3. Entity metadata + generic table from SPEC.md §3–§4 (registry, migrations, seeded rows).
4. Generic record form — typed inputs, validation, relations, bulk actions.
5. Audit trail — atomic writes for every mutation, change history, /audit.
6. Dashboard + global search — KPIs, recent activity, cross-entity search.
7. Import / export — streaming CSV export, mapped import with dry-run.
8. Quality — tests, CI, README quickstart, .env.example, accessibility.

The full rationale and the acceptance criteria live in SPEC.md §8–§9.

Working rules

• One concern per commit, conventional messages (feat:, fix:, chore:, docs:, test:).
• The CRUD surface is generated from entity metadata — add a field in the registry, never a new per-entity screen.
• Authorize every entity+action on the server; never only in the UI; keep every list query paginated and bounded.
• Write the audit record atomically with the mutation it describes; never update or delete an audit event.
• Runtime data is real typed records — never floating-point for money/quantities and never a schemaless blob where a FieldDefinition should drive validation.
• Never commit secrets — document them in .env.example instead.
• Keep docs/PLAN.md, the board and .w4c/project.json in sync as the project evolves.