techbro 0.0.0-stage → 0.5.0

package/templates/_default/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+members = ["apps/backend"]
+resolver = "2"

package/templates/_default/README.md

@@ -0,0 +1,257 @@
+# Engineering Convention
+
+Version: 1.0  
+Updated: 2026-10-08
+
+## Purpose and scope
+
+This convention defines how new software is built and maintained. It applies to developers, nontechnical contributors, and coding agents. Follow these defaults without requesting technical approval for routine implementation work.
+
+**MUST** means required. **SHOULD** means the default, with a documented reason for a different choice. **MAY** means optional.
+
+For an existing project, preserve its established stack and conventions. Do not rewrite or upgrade it simply to match this document. Explicit project instructions take precedence; conflicts affecting schemas, API contracts, or high-risk work require tech team review.
+
+## 1. Default stack
+
+| Area | Default |
+| --- | --- |
+| Frontend language | Plain JavaScript with JSX; no TypeScript by default |
+| Frontend framework | React |
+| Frontend build tool | Vite |
+| Frontend routing | React Router with path-based URLs (`/items`, `/items/:id`); no hash routing |
+| Backend architecture | Modular monolith: one process, one database, modules inside the app; no microservices by default |
+| Styling | Tailwind CSS |
+| UI components | shadcn/ui configured for JavaScript |
+| Backend language | Rust |
+| Backend HTTP framework | Axum |
+| Backend async runtime | Tokio |
+| JSON serialization | Serde |
+| Database access | SQLx with explicit SQL |
+| Local development and lightweight database tests | SQLite |
+| Shared environments and production | PostgreSQL |
+| JavaScript package manager | npm |
+| Rust package manager | Cargo |
+| Frontend checks | ESLint, Prettier, Vitest; React Testing Library for component tests |
+| Backend checks | rustfmt, Clippy, cargo test |
+| Testing approach | Test-driven: failing test first, then the smallest passing change, then refactor |
+| Deployment model | Blue/green, zero downtime: stateless process, `/ready` drain on `SIGTERM`, backward-compatible migrations and APIs |
+| Backend structured logging | tracing with JSON output |
+
+Plain JavaScript means JavaScript rather than TypeScript; React, JSX, and build tooling remain allowed. Do not introduce Next.js, an ORM, another language, or another architecture without a concrete need and an approved exception.
+
+Axum, Tokio, and SQLx are the recommended backend defaults adopted by this convention. Keep their configuration minimal.
+
+## 2. Versions and reproducibility
+
+- New projects MUST use the latest stable, mutually compatible releases available at setup time. Use the current Node.js LTS release and stable Rust toolchain.
+- Record exact toolchain versions in project configuration, including `rust-toolchain.toml` and a Node version file or equivalent.
+- Commit `package-lock.json` and `Cargo.lock` for applications. Use `npm ci` and locked Cargo operations in CI.
+- Do not resolve floating `latest` versions on each build. Upgrade deliberately, run checks, and commit the resulting version changes.
+- Avoid prerelease dependencies unless explicitly required.
+
+## 3. Architecture
+
+- A new product MUST use a monorepo with a React frontend and one Rust backend application by default.
+- Build a modular monolith, not microservices. One backend process, one database, one deployable. Separate concerns with modules inside the application (`models/`, `controllers/`, `views/`), not with separate services or network boundaries.
+- Splitting a service out requires a concrete, measured reason (for example independent scaling, a hard isolation requirement, or a separate team owning a separate release cadence) and an approved exception recorded in `docs/decisions/`. "It might need to scale later" is not a reason.
+- Use simple MVC responsibilities. A monorepo describes repository organization; it does not require microservices or multiple backend processes.
+- Keep controllers thin, business rules in model modules, and presentation in views.
+- Add small service modules only when they clarify business logic shared by multiple controllers. Do not create mandatory layers for every operation.
+- Do not introduce microservices, event sourcing, CQRS, generic repository frameworks, or elaborate dependency injection unless explicitly requested.
+- Prefer the smallest implementation that satisfies the current requirement and remains readable.
+
+### MVC responsibilities
+
+| Responsibility | Frontend | Backend |
+| --- | --- | --- |
+| Model | Data transformations and client state | Business rules, domain types, and persistence functions |
+| View | React components and pages | JSON response representations; templates only if needed |
+| Controller | Hooks and event handlers coordinating user actions and API calls | Axum handlers coordinating input, models, and responses |
+
+Frontend navigation uses React Router in browser-history mode. Register routes in one place (`src/routes.jsx`), use path-based URLs that mirror backend resource names, and serve the SPA with a history fallback so deep links load directly. Do not use hash-based URLs or hand-written `window.location` switching.
+
+React is component based. Apply MVC separation without forcing every component into three files. The backend remains authoritative for business validation and permissions. Frontend code MUST NOT connect directly to the database.
+
+## 4. Repository organization
+
+Use the following locations as a starting point. Create folders only when they contain meaningful code.
+
+| Path | Purpose |
+| --- | --- |
+| `apps/frontend/src/components/` | Reusable React components, including `ui/` for shadcn/ui |
+| `apps/frontend/src/pages/` | Page views, one component per route |
+| `apps/frontend/src/routes.jsx` | Route registration (React Router) |
+| `apps/frontend/src/hooks/` | Controller-style coordination and reusable hooks |
+| `apps/frontend/src/models/` | Client state helpers and data transformations |
+| `apps/frontend/src/api/` | HTTP client functions |
+| `apps/backend/src/controllers/` | HTTP handlers |
+| `apps/backend/src/models/` | Business rules and persistence modules |
+| `apps/backend/src/views/` | Response representations when separate types help |
+| `apps/backend/src/routes.rs` | Route registration |
+| `apps/backend/src/config.rs` | Validated application configuration |
+| `database/migrations/postgres/` | PostgreSQL SQL migrations |
+| `database/migrations/sqlite/` | SQLite SQL migrations, when SQLite is supported |
+| `scripts/` | Small development, checking, and migration commands |
+| `docs/api/` | API contract and examples |
+| `docs/decisions/` | Significant decisions and approved exceptions |
+
+Tests MAY live beside source files or in dedicated test folders. Choose one consistent arrangement per application. Avoid unused scaffolding and vague dumping grounds such as large `utils` modules.
+
+## 5. Programming style
+
+- Favor modular, functional code and composition. Keep functions focused and side effects explicit.
+- Use React function components and hooks.
+- Use classes in JavaScript only when they make stateful behavior clearer; avoid deep inheritance.
+- In Rust, use structs, enums, methods, and traits where appropriate. Do not recreate class inheritance patterns.
+- Prefer explicit data flow over global mutable state, hidden behavior, and clever abstractions.
+- Keep SQL, HTTP handling, and UI rendering out of unrelated business functions.
+
+## 6. Reuse and dependencies
+
+- Check existing project components, helpers, endpoints, and dependencies before adding replacements.
+- Use Tailwind utilities and existing shadcn/ui components before building another UI system. Generate JavaScript components rather than introducing TypeScript files.
+- Add third-party dependencies case by case. Document the purpose, alternatives considered, license suitability, maintenance status, and material security or operational impact in the pull request.
+- A small, established dependency within the approved stack MAY be added through normal review. Stack changes and dependencies affecting authentication, sensitive data, infrastructure, or major ongoing cost require tech team review.
+- Do not add a dependency for a trivial task that is clearer with a small amount of ordinary code.
+
+## 7. Database access
+
+- Use SQLx and parameterized SQL. Never construct queries by concatenating untrusted input.
+- Keep database access inside backend model/persistence modules, not controllers or frontend code.
+- Use transactions for related writes that must succeed or fail together. Enforce integrity with appropriate constraints and indexes.
+- Use SQLite for local workflows and lightweight tests; use PostgreSQL for shared environments and production.
+- SQLite is not proof of PostgreSQL compatibility. PostgreSQL-bound changes MUST be verified against PostgreSQL when they affect queries, migrations, constraints, concurrency, or database-specific behavior.
+- Keep business rules independent of database-specific SQL where practical. Do not build a generic database abstraction solely to conceal SQL differences.
+
+## 8. Independent database migrations
+
+Migrations MUST be deployable independently of the application process.
+
+- Store ordered, version-controlled SQL files under `database/migrations/`, outside application source directories.
+- Use SQLx CLI as the default migration runner. Provide documented commands such as `db:migrate:postgres` and `db:migrate:sqlite`, each supplying the correct migrations directory and connection configuration.
+- The migration command MUST run without starting or building the backend application. Do not automatically migrate on application startup.
+- Use separate engine-specific migration directories where SQL differs. Keep the intended logical schema aligned and document differences.
+- Use ordered names such as `20261008120000_create_users.sql`. Once applied to a shared environment, a migration MUST NOT be edited or deleted; add a corrective migration.
+- Use the runner's migration history and locking support. Run one migration job per target database; do not rely solely on naming order to prevent concurrent execution.
+- Validate migrations on a fresh database and on the previous supported schema. Test the actual target engine.
+- Prefer backward-compatible changes: add new structures, migrate data, update the application, then remove obsolete structures in a later approved change.
+- For destructive changes, document backup/recovery, compatibility, and data transformation before execution. Do not assume reversing a migration can restore deleted data.
+- Schema changes require tech team approval before implementation. Executing a destructive migration requires explicit authorization for the target environment.
+
+## 9. Communication and REST APIs
+
+- Use HTTP REST APIs with JSON first. Introduce events, queues, WebSockets, or background jobs only for a concrete requirement.
+- Use plural resource nouns and predictable routes, for example `GET /api/v1/users` and `PATCH /api/v1/users/{id}`.
+- Use HTTP methods and status codes consistently. Do not return `200` for failed operations.
+- Validate request bodies, parameters, and query strings on the backend. Frontend validation improves usability but does not replace backend validation.
+- Use consistent JSON naming: `camelCase`. Map Rust's internal `snake_case` fields through serialization configuration.
+- Use UTC ISO 8601 timestamps. Choose and document identifier and pagination formats.
+- Return resource objects directly by default. Collections SHOULD use `{ "items": [], "pagination": {} }` with documented pagination fields.
+- Use a consistent error shape: `{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "details": [] }, "requestId": "..." }`. Omit optional details when unnecessary; never expose internals.
+- Document endpoints, permissions, inputs, outputs, errors, and examples in a machine-readable OpenAPI contract where practical.
+- New or changed API contracts require tech team approval before implementation. Keep compatible changes within the current version; explicitly version approved breaking changes.
+- Calls to external services SHOULD use timeouts. Retry only when safe; do not automatically retry non-idempotent writes without a deliberate duplicate-prevention strategy.
+
+## 10. Security baseline
+
+Use established security practices with safeguards proportionate to the application. Additional hardening is added when requested or justified by actual exposure; these baseline requirements always apply.
+
+- Enforce authentication where required and authorization on the backend for every protected operation, including access to individual records.
+- Reuse approved authentication solutions. Do not invent cryptography or custom token schemes.
+- Never commit secrets or put private credentials in frontend bundles. Use injected configuration and keep local secret files out of version control.
+- Validate input, parameterize SQL, and avoid unsafe HTML rendering.
+- Use HTTPS for exposed applications and secure session/cookie settings where applicable. Apply CSRF protection when the authentication method requires it.
+- Restrict cross-origin access to intended clients. Do not use unrestricted credentialed access.
+- Never log passwords, tokens, database credentials, or unnecessary personal data.
+- If passwords are stored, use an established password-hashing library with appropriate settings.
+- Authentication, permission, sensitive-data, payment, and security-boundary changes are high-risk and require tech team involvement.
+
+## 11. Naming, formatting, and comments
+
+- Frontend: `camelCase` for variables/functions, `PascalCase` for React components, and consistent filenames matching their primary export.
+- Backend: standard Rust naming, rustfmt, and Clippy. Avoid unchecked `unwrap()`/`expect()` in request paths; handle failures explicitly.
+- Run ESLint and Prettier for frontend code. Do not disable checks broadly to make a change pass.
+- Use JSDoc for exported frontend functions, shared data shapes, and non-obvious interfaces. Document parameters, return values, and meaningful behavior. Do not comment every obvious line.
+- Use Rust documentation comments for public interfaces when they need explanation.
+- Comments SHOULD explain intent, constraints, or surprising behavior. Keep them accurate as code changes.
+
+## 12. Testing and mandatory checks
+
+- Work test-first (TDD) for business behavior: write a failing test that states the expected outcome, make it pass with the smallest change, then refactor with the test green. Commit the test with the code it covers.
+- Start from the outside in: an integration test on the HTTP contract (`tests/api.rs` or a Vitest page test) for the feature, then unit tests on model functions for validation rules and edge cases. Bug fixes begin with a test that reproduces the bug.
+- Keep tests fast and isolated: SQLite in memory for backend tests, mocked `fetch` for frontend API tests, no shared mutable state between tests. A test that needs a running service or network is an integration check, not part of the unit baseline.
+- Linting and unit tests MUST pass before every push. Provide a pre-push hook and equivalent CI checks; CI remains authoritative.
+- Frontend baseline: formatting check, ESLint, and Vitest. Backend baseline: `cargo fmt --check`, `cargo clippy --locked --all-targets -- -D warnings`, and `cargo test --locked`.
+- Verify application builds before merging a releasable change.
+- New or changed business behavior SHOULD have meaningful unit tests; bug fixes SHOULD include a regression test where practical.
+- Choose additional component, integration, API, and end-to-end tests case by case according to risk. Database and migration changes require target-engine integration checks.
+- Test outcomes and failure cases rather than implementation details. Do not add low-value tests simply to increase coverage.
+- No universal coverage percentage is imposed by this document. Existing project thresholds remain in force.
+- Never bypass a failing check silently. Any emergency exception must be explicitly approved and recorded with follow-up work.
+
+## 13. GitFlow and review
+
+- `main` contains released code; `develop` contains integrated work for the next release.
+- Create `feature/<description>` branches from `develop` and merge through pull requests after checks pass.
+- Create `release/<version>` branches from `develop` for release preparation; merge the completed release into `main` and back into `develop`, and tag it.
+- Create `hotfix/<description>` branches from `main` for urgent released-code fixes; merge back into `main` and `develop`, including any active release branch as needed.
+- Do not push directly to protected branches. Follow the repository's reviewer and approval requirements.
+- Keep pull requests focused. Describe the resulting behavior, checks performed, and any schema/API/risk implications.
+- Routine work follows normal contributor review. Specialist tech team approval is required only at the boundaries defined below.
+
+## 14. Documentation and observability
+
+- Maintain a concise README covering setup, pinned tools, configuration variable names, running, checking, and independent migration commands.
+- Maintain API documentation and significant decision/exception records when those change.
+- Provide a lightweight `GET /health` endpoint for process liveness. It MUST NOT expose sensitive configuration or run migrations.
+- Add a separate readiness endpoint when traffic acceptance depends on database or other critical dependency availability. Keep dependency checks bounded and inexpensive.
+- Backend application logs MUST be JSON lines written to stdout, ready for later aggregation.
+- Include timestamp, severity, application name, event/message, and request ID where relevant. Log useful failures and request outcomes without secrets or full payloads by default.
+- Add advanced monitoring only when required. Hosting, deployment infrastructure, and rollback tooling are outside this convention's current scope.
+
+### Zero-downtime deployment readiness
+
+Applications are deployed blue/green: a new instance starts beside the old one, traffic switches once it is ready, and the old one drains. The code MUST make that safe regardless of the hosting platform.
+
+- The backend process is stateless. Sessions, uploads, caches, and queues live outside the process; two instances with the same configuration MUST be interchangeable.
+- All configuration comes from environment variables. The same image runs in every environment; no environment-specific build.
+- `GET /health` reports liveness plus the running `version` and `build` (git SHA injected at build time) so the serving instance can be identified. `GET /ready` returns `503` while dependencies are unavailable and while the process is draining.
+- Handle `SIGTERM` gracefully: flip readiness to `503`, wait a short configurable drain period so load balancers stop routing, finish in-flight requests, close the database pool, then exit `0`. Never exit immediately on `SIGTERM`.
+- Database migrations run before the new instance starts (section 8) and MUST be compatible with both the old and the new code while both are serving. Follow expand/contract: add, backfill, switch code, remove later.
+- API changes within a version MUST be backward compatible for the same reason; the old and new instances may answer requests from the same client during a cut-over.
+- Rollback is switching traffic back to the previous instance. Do not ship a change that cannot run beside its predecessor without an approved exception and a documented cut-over plan.
+- Multi-instance deployments require PostgreSQL; SQLite is single-process and not supported for shared environments.
+
+## 15. Decision boundaries for contributors and agents
+
+| Change | Authority |
+| --- | --- |
+| UI, internal refactoring, tests, documentation, or implementation using existing schemas and API contracts | Contributor/agent may proceed through normal review |
+| Small dependency within the approved stack | Case-by-case normal review; escalate material risk |
+| New/changed database schema or migration | Tech team approval before implementation |
+| New/changed API contract | Tech team approval before implementation |
+| Authentication, permissions, sensitive data, payments, destructive operations, or substantial availability/cost impact | Tech team approval before implementation or execution, as applicable |
+| Different stack, architecture, or exception to a required rule | Explicit approval from the tech team or responsible technical owner |
+
+Routine implementation does not need repeated permission. Existing approval for a specified schema, contract, or high-risk task covers implementation within that approved scope. Renew review when the scope materially changes.
+
+Nontechnical contributors and agents MUST identify whether a request crosses these boundaries before starting dependent work. They MAY continue independent, low-risk work while a technical decision is pending. Record approved exceptions, their rationale, and their scope in the pull request or decision log.
+
+## Completion checklist
+
+- The change follows the approved stack and simple MVC responsibilities.
+- Existing components and behavior were checked before adding replacements.
+- Required schema, API, and high-risk decisions have approval.
+- Formatting, linting, and unit tests pass before push; applicable builds and integration checks pass before merge.
+- API documentation, README instructions, and migration files reflect relevant changes.
+- No secrets or unnecessary sensitive data enter source, responses, or logs.
+- The pull request describes behavior and verification clearly.
+
+## Reference documentation
+
+- [Axum](https://docs.rs/axum/latest/axum/)
+- [SQLx](https://docs.rs/sqlx/latest/sqlx/)
+- [SQLx CLI and migrations](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/README.md)
+- [shadcn/ui JavaScript configuration](https://ui.shadcn.com/docs/javascript)
+
+These links explain the selected tools. The defaults and approval rules above are team policy, not requirements imposed by those tools.

package/templates/_default/TEMPLATE.md

@@ -0,0 +1,29 @@
+# Starting a project from this template
+
+1. Copy this folder to your new repository and `git init`.
+2. Rename the app: `name` in `package.json`, the `backend` package in `apps/backend/Cargo.toml`
+   (and `-p backend` mentions), and `APP_NAME` in `.env.example`.
+3. Run `scripts/setup` (creates `.env`, installs frontend deps, fetches crates; it prints how to
+   install the `sqlx` CLI if missing).
+4. Create the local database: `scripts/db-migrate sqlite` (or `postgres` with a Postgres `DATABASE_URL`).
+5. Run all checks: `scripts/check` (or `npm run check`).
+6. Optionally install the pre-push hook: `scripts/install-hooks` (runs `scripts/check` before push).
+
+Commit `Cargo.lock` and `apps/frontend/package-lock.json`.
+
+## Layout
+
+- `apps/frontend`, `apps/backend` - the two applications.
+- `database/migrations/{postgres,sqlite}` - SQL migrations, run independently via `scripts/db-migrate`.
+- `docs/getting-started.md` - walkthrough of the sample feature and how to add your own.
+- `docs/deployment.md` - blue/green zero-downtime deployment guarantees and cut-over steps.
+- `docs/docker.md` - Docker images and compose stacks (dev and prod example).
+- `docs/api`, `docs/decisions` - API contract and decision records.
+- [`.agents/skills/README.md`](.agents/skills/README.md) - portable agent skills and explicit loading instructions.
+- `.github/workflows/ci.yml` - CI; pin actions to commit SHAs for your team.
+
+## README.md
+
+`README.md` is the Engineering Convention. In a real project, replace it with a project README
+(setup, pinned tools, config variable names, running, checking, migration commands) and keep a
+link to the convention.

package/templates/_default/_dockerignore

@@ -0,0 +1,8 @@
+target
+node_modules
+apps/frontend/node_modules
+dist
+.git
+.env
+*.db
+local.db

package/templates/_default/_gitignore

@@ -0,0 +1,8 @@
+target/
+node_modules/
+dist/
+.env
+*.sqlite
+*.db
+.DS_Store
+coverage/

package/templates/_default/apps/backend/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "backend"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+axum = "0.8.9"
+dotenvy = "0.15.7"
+serde = { version = "1.0.229", features = ["derive"] }
+serde_json = "1.0.151"
+sqlx = { version = "0.9.0", default-features = false, features = ["runtime-tokio", "sqlite", "postgres", "any", "migrate", "derive"] }
+thiserror = "2.0.21"
+tokio = { version = "1.53.2", features = ["full"] }
+tower-http = { version = "0.7.1", features = ["cors", "trace"] }
+tracing = "0.1.44"
+tracing-subscriber = { version = "0.3.23", features = ["json", "env-filter"] }
+uuid = { version = "1.27.0", features = ["v4"] }
+
+[dev-dependencies]
+http-body-util = "0.1.5"
+tower = "0.5.3"

package/templates/_default/apps/backend/Dockerfile

@@ -0,0 +1,34 @@
+# Build from the template root: docker build -f apps/backend/Dockerfile -t backend .
+# No TLS crates in Cargo.lock, so no openssl build dependencies are needed.
+# rust-toolchain.toml is not copied: the base image tag pins the toolchain (keep it in sync).
+FROM rust:1.95-slim-bookworm AS dev
+RUN cargo install cargo-watch --locked
+WORKDIR /app
+CMD ["cargo", "watch", "-x", "run -p backend"]
+
+FROM rust:1.95-slim-bookworm AS builder
+WORKDIR /build
+
+# Dependency layer: build with stub sources so it is cached until manifests change.
+COPY Cargo.toml Cargo.lock ./
+COPY apps/backend/Cargo.toml apps/backend/Cargo.toml
+RUN mkdir -p apps/backend/src \
+    && echo 'fn main() {}' > apps/backend/src/main.rs \
+    && touch apps/backend/src/lib.rs \
+    && cargo build --release --locked -p backend
+
+COPY apps/backend/src apps/backend/src
+ARG BUILD_SHA=dev
+ENV BUILD_SHA=$BUILD_SHA
+RUN touch apps/backend/src/main.rs apps/backend/src/lib.rs \
+    && cargo build --release --locked -p backend
+
+FROM debian:bookworm-slim
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd --system --uid 10001 --no-create-home app
+COPY --from=builder /build/target/release/backend /usr/local/bin/backend
+USER app
+EXPOSE 8080
+CMD ["backend"]

package/templates/_default/apps/backend/README.md

@@ -0,0 +1,13 @@
+# Backend
+
+Rust, Axum, Tokio, SQLx (`AnyPool`: SQLite or PostgreSQL chosen by `DATABASE_URL`).
+
+Run (from the template root, after `scripts/db-migrate sqlite`):
+
+    cargo run -p backend
+
+Environment (see `.env.example`): `APP_NAME`, `APP_PORT`, `DATABASE_URL`, `RUST_LOG`,
+`CORS_ALLOWED_ORIGINS` (comma-separated, no wildcard).
+
+Checks: `cargo fmt --all --check`, `cargo clippy --locked --all-targets -- -D warnings`,
+`cargo test --locked`. The app never runs migrations; use `scripts/db-migrate`.

package/templates/_default/apps/backend/src/config.rs

@@ -0,0 +1,111 @@
+use std::env;
+
+use axum::http::HeaderValue;
+
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    #[error("missing environment variable {0}")]
+    Missing(&'static str),
+    #[error("invalid {name}: {reason}")]
+    Invalid { name: &'static str, reason: String },
+}
+
+#[derive(Debug, Clone)]
+pub struct Config {
+    pub app_name: String,
+    pub port: u16,
+    pub database_url: String,
+    pub cors_allowed_origins: Vec<HeaderValue>,
+    pub shutdown_drain_seconds: u64,
+}
+
+fn required(name: &'static str) -> Result<String, ConfigError> {
+    match env::var(name) {
+        Ok(v) if !v.trim().is_empty() => Ok(v.trim().to_string()),
+        _ => Err(ConfigError::Missing(name)),
+    }
+}
+
+impl Config {
+    pub fn from_env() -> Result<Self, ConfigError> {
+        let app_name = required("APP_NAME")?;
+        let port = required("APP_PORT")?
+            .parse::<u16>()
+            .map_err(|e| ConfigError::Invalid {
+                name: "APP_PORT",
+                reason: e.to_string(),
+            })?;
+        let database_url = required("DATABASE_URL")?;
+        let supported = ["sqlite:", "postgres:", "postgresql:"];
+        if !supported.iter().any(|p| database_url.starts_with(p)) {
+            return Err(ConfigError::Invalid {
+                name: "DATABASE_URL",
+                reason: "must start with sqlite:, postgres: or postgresql:".into(),
+            });
+        }
+        let cors_allowed_origins = parse_origins(&required("CORS_ALLOWED_ORIGINS")?)?;
+        let shutdown_drain_seconds = parse_drain(env::var("SHUTDOWN_DRAIN_SECONDS").ok())?;
+        Ok(Self {
+            app_name,
+            port,
+            database_url,
+            cors_allowed_origins,
+            shutdown_drain_seconds,
+        })
+    }
+}
+
+pub const DEFAULT_DRAIN_SECONDS: u64 = 5;
+
+pub fn parse_drain(raw: Option<String>) -> Result<u64, ConfigError> {
+    match raw.as_deref().map(str::trim).filter(|v| !v.is_empty()) {
+        None => Ok(DEFAULT_DRAIN_SECONDS),
+        Some(v) => v
+            .parse()
+            .map_err(|e: std::num::ParseIntError| ConfigError::Invalid {
+                name: "SHUTDOWN_DRAIN_SECONDS",
+                reason: e.to_string(),
+            }),
+    }
+}
+
+pub fn parse_origins(raw: &str) -> Result<Vec<HeaderValue>, ConfigError> {
+    raw.split(',')
+        .map(str::trim)
+        .filter(|o| !o.is_empty())
+        .map(|o| {
+            if o == "*" {
+                return Err(ConfigError::Invalid {
+                    name: "CORS_ALLOWED_ORIGINS",
+                    reason: "wildcard origin is not allowed".into(),
+                });
+            }
+            HeaderValue::from_str(o).map_err(|e| ConfigError::Invalid {
+                name: "CORS_ALLOWED_ORIGINS",
+                reason: e.to_string(),
+            })
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{parse_drain, parse_origins};
+
+    #[test]
+    fn drain_defaults_to_five() {
+        assert_eq!(parse_drain(None).unwrap(), 5);
+        assert_eq!(parse_drain(Some("12".into())).unwrap(), 12);
+        assert!(parse_drain(Some("x".into())).is_err());
+    }
+
+    #[test]
+    fn rejects_wildcard() {
+        assert!(parse_origins("*").is_err());
+    }
+
+    #[test]
+    fn parses_list() {
+        assert_eq!(parse_origins("http://a, http://b").unwrap().len(), 2);
+    }
+}

package/templates/_default/apps/backend/src/controllers/health.rs

@@ -0,0 +1,36 @@
+use std::{sync::atomic::Ordering, time::Duration};
+
+use axum::{Json, extract::State};
+use serde_json::{Value, json};
+
+use crate::{error::AppError, state::AppState};
+
+pub async fn health() -> Json<Value> {
+    Json(json!({
+        "status": "ok",
+        "version": env!("CARGO_PKG_VERSION"),
+        "build": option_env!("BUILD_SHA").unwrap_or("dev"),
+    }))
+}
+
+pub async fn ready(State(state): State<AppState>) -> Result<Json<Value>, AppError> {
+    if state.draining.load(Ordering::SeqCst) {
+        return Err(AppError::Draining);
+    }
+    let check = tokio::time::timeout(
+        Duration::from_secs(2),
+        sqlx::query("SELECT 1").execute(&state.pool),
+    )
+    .await;
+    match check {
+        Ok(Ok(_)) => Ok(Json(json!({ "status": "ready" }))),
+        Ok(Err(e)) => {
+            tracing::error!(error = %e, "readiness check failed");
+            Err(AppError::Unavailable)
+        }
+        Err(_) => {
+            tracing::error!("readiness check timed out");
+            Err(AppError::Unavailable)
+        }
+    }
+}

package/templates/_default/apps/backend/src/controllers/items.rs

@@ -0,0 +1,79 @@
+use axum::{
+    Json,
+    extract::{
+        Path, Query, State,
+        rejection::{JsonRejection, PathRejection, QueryRejection},
+    },
+    http::StatusCode,
+};
+use serde::Deserialize;
+
+use crate::{
+    error::AppError,
+    models::item::{self, Item},
+    state::AppState,
+    views::items::{ItemListResponse, Pagination},
+};
+
+const DEFAULT_PER_PAGE: i64 = 20;
+const MAX_PER_PAGE: i64 = 100;
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ListQuery {
+    page: Option<i64>,
+    per_page: Option<i64>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct CreateItem {
+    name: String,
+}
+
+pub async fn list(
+    State(state): State<AppState>,
+    query: Result<Query<ListQuery>, QueryRejection>,
+) -> Result<Json<ItemListResponse>, AppError> {
+    let Query(q) = query.map_err(|_| AppError::validation("query", "Invalid query string"))?;
+    let page = q.page.unwrap_or(1);
+    let per_page = q.per_page.unwrap_or(DEFAULT_PER_PAGE);
+    if page < 1 {
+        return Err(AppError::validation("page", "Must be at least 1"));
+    }
+    if !(1..=MAX_PER_PAGE).contains(&per_page) {
+        return Err(AppError::validation("perPage", "Must be between 1 and 100"));
+    }
+    let offset = (page - 1)
+        .checked_mul(per_page)
+        .ok_or_else(|| AppError::validation("page", "Too large"))?;
+    let (items, total) = item::list(&state.pool, per_page, offset).await?;
+    Ok(Json(ItemListResponse {
+        items,
+        pagination: Pagination {
+            page,
+            per_page,
+            total,
+        },
+    }))
+}
+
+pub async fn create(
+    State(state): State<AppState>,
+    body: Result<Json<CreateItem>, JsonRejection>,
+) -> Result<(StatusCode, Json<Item>), AppError> {
+    let Json(input) = body.map_err(|_| AppError::validation("body", "Invalid JSON body"))?;
+    let name = item::validate_name(&input.name)?;
+    let created = item::create(&state.pool, &name).await?;
+    Ok((StatusCode::CREATED, Json(created)))
+}
+
+pub async fn get(
+    State(state): State<AppState>,
+    id: Result<Path<i64>, PathRejection>,
+) -> Result<Json<Item>, AppError> {
+    let Path(id) = id.map_err(|_| AppError::validation("id", "Must be an integer"))?;
+    item::find(&state.pool, id)
+        .await?
+        .map(Json)
+        .ok_or(AppError::NotFound)
+}

package/templates/_default/apps/backend/src/controllers/mod.rs

@@ -0,0 +1,2 @@
+pub mod health;
+pub mod items;