update document

CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# Contributing to Avored Rust CMS
+
+Thanks for being interested in contributing to Avored Rust CMS. This project is a Rust workspace with an Axum backend, a Leptos SSR frontend, and a Vite/Tailwind asset pipeline. The guidance below is intended to keep local development predictable and make review easier for maintainers.
+
+## Before you start
+
+- Open or reference the relevant GitHub issue before starting larger work.
+- Keep changes small and scoped to the issue or feature you are addressing.
+- If a change affects public behaviour, update the relevant docs and examples.
+
+## Local setup
+
+### Prerequisites
+
+- Rust and Cargo
+- `wasm32-unknown-unknown` target
+- Node.js and npm
+- `cargo-leptos`
+
+Install the Rust target and Leptos tooling if needed:
+
+```bash
+rustup target add wasm32-unknown-unknown
+cargo install cargo-leptos --locked
+```
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Configure local environment
+
+Create a `.env` file in the project root with the same values used by the app locally:
+
+```dotenv
+APP_ENV=local
+AVORED_DATABASE_NAMESPACE=avored
+AVORED_DATABASE_NAME=avored_cms
+AVORED_DATABASE_FOLDER_NAME=rocksdb://data/avored.db
+AVORED_PASSWORD_SALT=replace-with-a-random-secret
+AVORED_JWT_SECRET=replace-with-another-random-secret
+AVORED_CORS_ALLOWED_APP_URL=http://localhost:3000
+```
+
+Generate unique random values with:
+
+```bash
+openssl rand -hex 32
+```
+
+Do not commit `.env` files. Keep production secrets out of the repository and use environment-specific files (`.env.dev`, `.env.test`, etc.) only when needed.
+
+### Run the app
+
+```bash
+npm run dev
+```
+
+This starts Vite and the Leptos development watcher. The application listens on port `3000` by default.
+
+## Project layout
+
+```text
+crates/
+  avored-api/      # Axum server, router registrations, HTTP handlers
+  avored-core/     # domain, DTOs, repo traits, app use cases
+  avored-web/      # Leptos UI and hydration-facing web components
+
+docs/
+  architecture/     # architecture and frontend hydration notes
+  roadmap/         # planning and backlog documents
+  tech-debt/        # debt and implementation follow-ups
+```
+
+## Development workflow
+
+### Rust
+
+Use the workspace default formatting and compile checks before submitting changes:
+
+```bash
+cargo fmt
+cargo test
+```
+
+If you are working on backend or API behaviour, prefer targeted integration tests where possible rather than broad, noisy test runs.
+
+### Frontend
+
+Use the project's Vite/Tailwind workflow when modifying styles or frontend assets:
+
+```bash
+npm run build
+```
+
+When adjusting Leptos components, keep SSR and hydration safety in mind. The project already documents the hydration boundaries in [docs/architecture/leptos-ssr-hydration-boundaries.md](docs/architecture/leptos-ssr-hydration-boundaries.md).
+
+## Coding standards
+
+- Prefer small, readable functions and domain-specific types.
+- Keep `Axum` handlers and `Leptos` views aligned with the existing project structure rather than introducing ad hoc patterns.
+- Add or update docs when a user-facing or developer-facing behaviour changes.
+- Make validation and error handling explicit, especially for HTTP and database failures.
+- Avoid leaking implementation details into end-user-facing error messages.
+
+## Pull request checklist
+
+Before opening a PR, confirm the following:
+
+- The change is scoped to a single issue or improvement.
+- The relevant tests or checks have been run.
+- The README or developer docs have been updated when needed.
+- The code is formatted and consistent with the existing Rust workspace style.
+- The description explains the user problem, the fix, and any follow-up work.
+
+## Useful references
+
+- [README](README.md)
+- [Architecture overview](docs/architecture/leptos-ssr-hydration-boundaries.md)
+- [API route/versioning reference](docs/api-route-versioning.md)
+- [Roadmap](docs/roadmap/improvement-and-tech-debt-roadmap.md)
+
+## Questions or help
+
+If you are unsure how to proceed, start by checking the existing docs and issue thread for the feature area you are working in. A focused question tied to the exact behavior or bug is usually the fastest way to unblock progress.

README.md

@@ -113,6 +113,17 @@ cargo install cargo-leptos --locked
 
 ---
 
+## Documentation
+
+New contributors should start here:
+
+- [Architecture overview](document/leptos-ssr-hydration-boundaries.md)
+- [API route/versioning reference](document/api-route-versioning.md)
+- [Roadmap and tech debt backlog](document/improvement-and-tech-debt-roadmap.md)
+- [Contributing guide](CONTRIBUTING.md)
+
+---
+
 ## Get started
 
 1. Clone the repository and enter the project directory:
@@ -210,10 +221,10 @@ Do not use development secrets in production. Set `APP_ENV=prod` in `.env` and p
 
 ## Contributing
 
-Contributions are welcome! Please open an issue to discuss the change you'd like to make before submitting a pull request. All code must pass `cargo test` and be formatted with `cargo fmt`.
+Contributions are welcome. Please read the [contributing guide](CONTRIBUTING.md) before opening a pull request. In short: open or reference an issue, keep changes small and scoped, update docs when behaviour changes, and ensure the relevant Rust and frontend checks pass.
 
 ---
 
 ## License
 
-This project is open-source. See the [LICENSE](LICENSE) file for details.
+This repository does not currently declare a license in its root metadata or files. Before redistributing or publishing forks, confirm the intended licensing terms with the project maintainers.

document/api-route-versioning.md

@@ -0,0 +1,38 @@
+# API Route Versioning
+
+## Policy
+
+All resource APIs use the `/api/v1/` prefix. Public API-key endpoints live directly under `/api/v1/`; JWT-protected browser administration endpoints live under `/api/v1/admin/`. Authentication/bootstrap endpoints (`/api/auth/login`, `/api/misc/setup`) and the operational health check (`/health`) are outside the resource API and are explicitly unversioned.
+
+JWT-protected admin routes require `Authorization: Bearer <JWT>`. Public entity-record routes require `X-Api-Key`. The API-key administration endpoints are admin-only and require a JWT. Admin routes do not accept API keys as a substitute for JWTs.
+
+## Canonical routes
+
+| Method | Path | Audience | Authentication |
+|---|---|---|---|
+| GET, POST | `/api/v1/admin/collection` | Admin browser | JWT |
+| GET, PUT, DELETE | `/api/v1/admin/collection/{record_id}` | Admin browser | JWT |
+| GET, POST | `/api/v1/admin/entities` | Admin browser | JWT |
+| GET, PUT, DELETE | `/api/v1/admin/entities/{id}` | Admin browser | JWT |
+| GET | `/api/v1/admin/entities/options` | Admin browser | JWT |
+| PUT | `/api/v1/admin/entities/{id}/identifier` | Admin browser | JWT |
+| GET, POST | `/api/v1/admin/email-templates` | Admin browser | JWT |
+| GET, PUT, DELETE | `/api/v1/admin/email-templates/{id}` | Admin browser | JWT |
+| GET, POST | `/api/v1/admin/workflows` | Admin browser | JWT |
+| GET, PUT, DELETE | `/api/v1/admin/workflows/{id}` | Admin browser | JWT |
+| PATCH | `/api/v1/admin/workflows/{id}/active` | Admin browser | JWT |
+| GET | `/api/v1/admin/workflows/{id}/executions` | Admin browser | JWT |
+| GET, POST | `/api/v1/admin/api-keys` | Admin browser | JWT |
+| GET, PUT, DELETE | `/api/v1/admin/api-keys/{id}` | Admin browser | JWT |
+| GET, PUT | `/api/v1/admin/me` | Admin browser | JWT |
+| PUT | `/api/v1/admin/me/password` | Admin browser | JWT |
+| GET, PUT | `/api/v1/admin/settings` | Admin browser | JWT |
+| GET, POST | `/api/v1/entities` | Public API | `X-Api-Key` |
+| GET, PATCH, DELETE | `/api/v1/entities/{id}` | Public API | `X-Api-Key` |
+| POST | `/api/auth/login` | Authentication | None |
+| POST | `/api/misc/setup` | Initial setup | None |
+| GET | `/health` | Operations | None |
+
+## Compatibility
+
+Admin routes are consumed by this repository's own browser client. Legacy unversioned admin paths and `/api/v1/settings` are removed; clients in this repository use the canonical routes above. No deprecation or sunset window is maintained.