# Repository Guidelines

## Overview
Warden is a minimal, Bitwarden-compatible backend that runs on Cloudflare Workers (inspired by Vaultwarden).
This repository does **not** reuse Vaultwarden code: `vaultwarden/` is for reference only.
The bundled web UI is shipped as prebuilt artifacts under `public/web-vault/`.
It typically should not be edited.
Unsupported/"won't implement" features are listed in `README.md`.

## Project Structure & Module Organization
- `src/`: Rust backend (Axum router + request handlers).
  - `src/handlers/`: endpoint implementations grouped by feature.
  - `src/models/`: request/response payload types.
  - `src/durable/`: Durable Object(s) (e.g., `HeavyDo`) to offload CPU-heavy endpoints.
    - `HeavyDo` directly reuses the existing Axum router/handlers stack (no duplicated business logic).
- `src/entry.js`: Wrangler entrypoint (routing + R2 attachment streaming + optional DO offload).
- `migrations/`: D1 migrations applied via Wrangler.
- `sql/`: base schema (`sql/schema.sql`) and optional seed SQL.
- `scripts/`: helper scripts (apply web-vault overrides, seed equivalent domains).
- `docs/`: deployment and D1 backup/restore playbooks.

## Build, Test, and Development Commands
Prereqs: Rust toolchain from `rust-toolchain.toml`, Node.js, and Wrangler.
- `cargo fmt` / `cargo fmt -- --check`: format Rust.
- `cargo clippy --target wasm32-unknown-unknown --no-deps`: lint for the Workers WASM target.
- `cargo test`: run unit tests (currently none).
- Local dev: `wrangler dev --local --persist-to .wrangler/state`.
- Apply migrations (remote): `wrangler d1 migrations apply vault1 --remote`.
- Deploy: `wrangler deploy` (or `wrangler deploy --env dev`).

## Coding Style & Naming Conventions
- Rust: keep routing in `src/router.rs` and endpoint logic in `src/handlers/*`.
- Rust formatting: `rustfmt` (default settings).
- JS: keep edge-only concerns in `src/entry.js` (streaming, request sharding/offload).
- Naming: Rust `snake_case`; files follow feature names (e.g., `handlers/ciphers.rs`).

## Testing Guidelines
There is no established test suite yet.
If adding tests, prefer unit tests in-module (`#[cfg(test)] mod tests`).
Avoid Cloudflare bindings/network.

## Commit & Pull Request Guidelines
- Commits follow Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`.
- PRs should describe behavior changes and list operational impacts:
  D1 migrations, new env vars/secrets, R2/DO bindings.

## Security & Configuration
- Do not commit secrets.
  Use `.env` locally and Cloudflare/GitHub Secrets for deploy:
  `JWT_SECRET`, `JWT_REFRESH_SECRET`, `D1_DATABASE_ID`.