fullstack-webapp

Imported from ZetaTwo/dotfiles (.claude/skills/fullstack-webapp/SKILL.md). Install upstream with npx skills add ZetaTwo/dotfiles --skill fullstack-webapp. Copyright stays with the author.

Full-stack web app (Rust/axum + Vue/TS + Postgres)

The user's house style for web apps, distilled from a working project (canst). Follow it by default; deviate only when a project needs it, and then record the deviation (see Keeping this skill current at the bottom).

If invoked with the argument sync, skip straight to Sync mode below.

Stack

Versions are what canst used; bump to latest stable when starting fresh.

Repo layout

backend/
  Cargo.toml  diesel.toml  .gitignore(target/)
  config/local.example.toml        # committed; local.toml is gitignored
  migrations/                      # diesel CLI timestamped dirs, up.sql + down.sql
  src/
    main.rs        # clap --config, tracing init, prints StartupError via Display
    lib.rs         # AppState, FromRef impls, build_router(state) — shared by main and tests
    config.rs      # Config (serde from TOML)
    startup.rs     # StartupError (never becomes an HTTP response)
    error.rs       # AppError -> JSON {error, code}
    authz.rs       # Capability, Read/Edit/Delete, Authorized<T, C>, authorize_* fns
    api_types.rs   # path-param newtypes for the OpenAPI macro (UuidParam)
    auth/{mod,paseto,password,session}.rs
    db/{mod,schema}.rs             # pool, DbConn extractor, MIGRATIONS; schema.rs is generated
    models/<resource>.rs           # Queryable/Selectable row, Insertable New*, request/response DTOs
    routes/<resource>.rs           # one router() per resource
  tests/
    common/mod.rs  # TestApp harness (mod.rs so cargo doesn't treat it as a test binary)
    api.rs         # integration suite
frontend/
  index.html (data-theme on <html>)  vite.config.ts  package.json  playwright.config.ts
  e2e/                             # Playwright: run.sh, fixtures.ts, stub-server.mjs, *.spec.ts
  src/
    main.ts  App.vue  style.css
    api/{client,types}.ts
    stores/<resource>.ts
    router/index.ts
    views/<Name>View.vue
    components/
    theme/theme-base.css  theme/theme-<name>.css
    **/*.test.ts                   # Vitest unit/component tests, next to the code
.gitignore   # /target, /backend/config/local.toml, /frontend/node_modules, /frontend/dist
CLAUDE.md    # includes "## Deviations from fullstack-webapp"

Principles

Config & secrets

• Secrets live only in a gitignored TOML file (backend/config/local.toml) whose path is passed as --config <path>. No env vars for config or secrets; RUST_LOG is the only exception. Commit local.example.toml with placeholders and the command that generates each secret (openssl rand -base64 32).
• Every external HTTP endpoint the app calls is a Config field with a #[serde(default = ...)] pointing at the real URL. That field is how tests swap in a wiremock server.
• auto_migrate: bool (default false) is a dev-only shortcut that runs embedded migrations at startup.
• log_format (text by default) can be set to json when the deploy environment's log pipeline wants JSON lines (.json().flatten_event(true), so level/message are top level). Only set it if that environment actually parses JSON.

Operational hooks (every app has these, wherever it ends up running)

• <app>-backend --config <path> migrate applies the embedded migrations and exits. The default (no subcommand) runs the server. Migrations run as their own step before a new version starts, never implicitly at server startup outside dev.
• GET /api/healthz round-trips the database (SELECT 1 via DbConn) and returns 200, or 503 when the pool can't get a connection. It's a plain .route(), not an #[endpoint].

Dev setup

• Dev uses a Postgres installed locally, not Docker. Docker/Podman is needed only for cargo test (testcontainers).
• The app assumes a single origin, so cookie auth needs no CORS: the SPA and /api are served from the same host. In dev, Vite on :5173 proxies /api to axum on :3000. axum serves only the API and never static files; whatever hosts the app routes /api to it.

Out of scope: deployment (containers, hosting, proxies, deploy pipelines, backups) is not part of this skill. Running the test suites in CI is in scope. If the user has an infrastructure repo, follow its documentation for how apps get deployed.

Backend structure

• Each handler declares its full absolute /api/... path in #[endpoint], and sub-routers are combined with .merge(), not .nest(). Nesting would double the prefix and break the OpenAPI spec.
• Request guards are axum extractors: DbConn (pool exhaustion → 503), Session (401 if missing/invalid), OptionalSession (infallible). A handler's signature states what it needs.
• The backend is the real gate. Per-object checks use Authorized<T, C>, which can only be built by an authorize_* fn, so any function taking Authorized<T, Edit> is statically known to have run the check. List endpoints authorize through their WHERE clause. All-admin route groups use one route_layer(middleware::from_fn_with_state(state, require_admin)).
• Handlers have the shape async fn x(State, Path?, Session?, DbConn, Json?) -> Result<Json<T>, AppError>.
• AppError maps to (status, Json({error, code})). 4xx variants return their hand-written Display text. 5xx variants return a fixed generic message and log the full source() chain through tracing::error!. StartupError is a separate enum, and main prints it with Display.
• Map known DB constraint violations (e.g. UniqueViolation on <table>_<col>_key) to specific Conflict messages, and fall back to a generic message for unknown ones.
• Risky or unfinished features go behind a Cargo feature that is off by default, gating both the mod and the .merge() with #[cfg(feature = "...")].

Data modeling

• Use UUID PKs (gen_random_uuid()), TIMESTAMPTZ NOT NULL DEFAULT now(), and an index for each query shape you actually run.
• For case-insensitive text (usernames, emails), use an ICU nondeterministic collation (case_insensitive), not CITEXT.
• Fixed value sets use a PG enum + DbEnum + #[serde(rename_all = "lowercase")]. Sets that users/admins may extend get a lookup table with an FK, so adding a value needs no migration.
• Derive state instead of storing it. Don't add a status column that could contradict other columns (e.g. published = scheduled_date <= today). Encode allowed row shapes as CHECK constraints.
• Prefer simple SQL that is correct by construction (ORDER BY random(), EXISTS anti-joins) over app-layer logic, and note any perf caveat you are accepting.

Auth

• PASETO v4.local tokens in HttpOnly+Secure cookies: a 15-min access token (path=/, SameSite=Lax) and a 30-day refresh token (path=/api/auth/refresh, SameSite=Strict), rotated on refresh. users.token_generation is embedded in both tokens; logout-all increments it, which revokes every outstanding refresh token.
• Passwords use argon2id with default params. There is no admin bootstrap route: promote the first admin with SQL.

API contract

• The OpenAPI spec is generated from the code. The TS client is hand-written: api/types.ts mirrors the Rust DTOs by convention, with a header comment saying so. Check it against /api/openapi.json when it drifts.
• Never serialize DB row structs that hold secrets. Use a response DTO with From<Row> (e.g. User → UserResponse).

Frontend

• api/client.ts is a thin fetch wrapper with credentials: 'include'. It throws ApiError(status, code) and treats 204 as undefined.
• Pinia setup stores (defineStore('x', () => {...})) expose loading/notFound-style refs. Refetch on view entry whenever server data is non-deterministic (e.g. randomized).
• The router lazy-loads views and uses meta.requiresAuth. beforeEach bootstraps the auth store once via GET /api/auth/me. Guards are UX only.
• Theming: theme-base.css declares the custom-property contract with no values, and each theme-<name>.css supplies values under :root[data-theme='<name>'], including a prefers-color-scheme: dark block. Components use only var(--...) and never branch on the theme.
• When the UI varies by a discriminator (e.g. platform/kind), one component switches on it and the variant components stay unaware of each other.

Testing

• Integration tests run against a real Postgres via testcontainers, never mocked Diesel. They use the same build_router, driven by tower::ServiceExt::oneshot, with no socket.
• Outbound HTTP is pointed at wiremock via TestApp::spawn_with_config. Tests must never hit the real internet.
• Unit tests for pure logic go in #[cfg(test)] mod tests next to the code: token round-trips and rejection, password hash/verify, error-body shape, URL parsing.
• Measure coverage with cargo llvm-cov. Test each Cargo feature both enabled and disabled.
• Frontend unit/component tests (Vitest, pnpm test) sit next to the code as *.test.ts. They cover the API client's session logic (401 → refresh → replay) against a stubbed fetch, stores with the api module mocked, and components through @vue/test-utils.
• Browser tests (Playwright, pnpm test:e2e) drive real Chrome against the production build, the real backend binary and a real Postgres, one clean database per test. They are hermetic: a local stub server stands in for third parties the backend calls (via the same Config endpoint fields), context.route() stubs widget scripts, and every other outbound request is blocked.
• Run all three suites in CI before anything ships.

Reference files — read before writing the matching code

The snippets are real, working code with the domain types renamed. Adapt them; don't paste placeholder names into a real project.

New-project checklist

1. cargo new backend --lib (add src/main.rs) and set up the deps from backend-core.md. cargo install diesel_cli --no-default-features --features postgres if missing.
2. Write config/local.example.toml, .gitignore entries, config.rs, startup.rs, error.rs, db/mod.rs, lib.rs, and main.rs.
3. createuser <app> --pwprompt && createdb <app> --owner=<app>. Copy the example config to local.toml and fill it in.
4. diesel setup, then add migrations: the collation, then users (with is_admin, token_generation). Run diesel migration run, which writes src/db/schema.rs.
5. Write the auth module and auth routes (register/login/refresh/logout/logout-all/me), plus authz.rs.
6. Write tests/common/mod.rs and a first tests/api.rs covering an empty-DB smoke test, /api/healthz, the OpenAPI document being well formed, and the auth flow. Check that cargo run -- --config config/local.toml migrate works.
7. Scaffold the frontend: pnpm create vite@latest frontend -- --template vue-ts, then pnpm add vue-router pinia. Add the Vite proxy, api/client.ts, api/types.ts, the auth store, the router, and the theme files. Then set up both test layers from reference/frontend-testing.md: Vitest with the client's refresh tests, and Playwright with e2e/run.sh, the fixtures, a stub server for each third party, and a first auth/session spec.
8. Add resources one at a time with the checklist below, pairing each backend resource with its frontend view.
9. README: prerequisites, DB setup, run, test (incl. DOCKER_HOST for rootless podman), coverage, and feature flags.
10. Create a project CLAUDE.md containing an empty ## Deviations from fullstack-webapp section.

Add-a-resource checklist

1. diesel migration generate create_<things>: write up.sql (CHECKs, indexes) and down.sql, then run diesel migration run.
2. models/<thing>.rs: a row struct (Queryable, Selectable, check_for_backend(Pg)), New<Thing> (Insertable), request DTOs (Deserialize, ToSchema), and enums (DbEnum).
3. If rows are loaded by id and need owner checks, add authorize_<thing>_{read,edit,delete} in authz.rs.
4. routes/<thing>.rs: router() with .add(handler()), using #[endpoint] with an absolute path. Add .merge(routes::<thing>::router()) in build_router.
5. Integration tests in tests/api.rs covering the happy path, anonymous 401, cross-user 403, admin override, and 404.
6. Frontend: add types to api/types.ts, then the store, the view, the route, and the nav link.
7. Frontend tests: store and component tests for the new logic, and a Playwright spec for the resource's UI flows. Cover the happy path, its server-side errors as shown in the UI, and visibility/authorization across two users.

Keeping this skill current

Rule (always on). When working in a project built with this skill, a decision may contradict or extend a convention above, for example a different library, a new cross-cutting pattern, or a changed default. When that happens:

1. Append one line to the project's CLAUDE.md under ## Deviations from fullstack-webapp (create the section if missing). Format: - YYYY-MM-DD — <decision> — <why> — <skill section it affects>.
2. Ask the user whether this should become the new default in the skill. Edit files under ~/.claude/skills/fullstack-webapp/ only after an explicit yes. If they say yes, apply the edit and append (merged into skill YYYY-MM-DD) to the entry. Project-specific choices stay as deviations only.

Sync mode (/fullstack-webapp sync).

1. Read the current project's CLAUDE.md ## Deviations from fullstack-webapp section. If it is missing or every entry is already merged or rejected, say so and stop.
2. For each open entry, find the affected section in SKILL.md and/or reference/*.md. If that project's code shows how the decision was implemented, read it so any reference snippet you write is real code.
3. Present the proposed edits one entry at a time (show the diff) and ask: merge, reject, or skip.
4. Apply the approved edits. Annotate each entry with (merged into skill YYYY-MM-DD) or (rejected for skill YYYY-MM-DD), and leave skipped entries untouched.
5. Keep SKILL.md concise. Detail belongs in reference/. When a new default replaces an old one, delete the old text rather than keeping both.

~/.claude is versioned in the user's dotfiles repo, so the skill needs no separate history.