091ac3499f
Source: templates/admin-dashboard (12 file(s) mirrored) - README.md - .editorconfig - .gitignore
65 lines
3.6 KiB
Markdown
65 lines
3.6 KiB
Markdown
# 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`](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`](.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.
|