# CLAUDE.md

## Project

Web app that answers one question with data: for a given property in France, is buying
financially better than renting and investing the same cash? It outputs an amortisation
schedule, total ownership costs, and breakeven curves under several market hypotheses.

This is a financial tool. A wrong number is worse than a slow response, an ugly page, or a
missing feature. Correctness and traceable sources come first.

I am learning Rust through this project. See "Working with me" below.

## Commands

```bash
cargo run -p immo-web                   # start the server on :3000
cargo watch -x 'run -p immo-web'        # live reload during development
cargo test --workspace                  # all tests
cargo test -p immo-core                 # domain tests only, fast
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
```

Run `cargo clippy` and `cargo test -p immo-core` before telling me a change is finished.

## Architecture boundary

Two crates. The boundary is a rule, not a description.

`crates/immo-core` holds all financial logic as pure functions over plain structs.

- No `tokio`, no `axum`, no `reqwest`, no filesystem, no network access.
- Must stay compilable to `wasm32-unknown-unknown`. After adding any dependency, verify with
  `cargo check -p immo-core --target wasm32-unknown-unknown`.
- Time is a parameter. Never call `Utc::now()` or read the system clock inside `immo-core`.

`crates/immo-web` holds HTTP, HTML rendering, and input parsing. It contains no financial
arithmetic.

If a computation is tempting to write inline in a handler, it belongs in `immo-core`.

## Stack, pinned

- axum 0.8. Path parameters use `{param}`, **not** `:param` — that is 0.7 syntax and will not compile.
- `#[async_trait]` is not needed on `FromRequest` / `FromRequestParts` in 0.8. Do not add it.
- askama for templates, tower-http for static files and compression, serde, rust_decimal.
- Server-rendered HTML. No npm, no bundler, no JS framework. Charts are a CDN `<script>` tag fed
  by a JSON endpoint.

Before writing axum code from memory, check the version in `Cargo.toml` and verify the API against
docs.rs for that exact version.

## Domain rules

- Money is `rust_decimal::Decimal` or integer cents. Never `f64`. Never `as` casts between numeric
  types in financial code.
- Rates are stored as annual nominal and converted explicitly. Name variables so the period is
  unambiguous (`taeg_annual`, `monthly_rate`), never a bare `rate`.
- Keep French domain vocabulary in type and field names: `FraisDeNotaire`, `TaxeFonciere`,
  `IndiceReferenceLoyers`, `LoyerDeReferenceMajore`, `ZoneTendue`, `Taeg`. Do not translate them.
- Every hardcoded assumption lives in `crates/immo-core/src/assumptions.rs` with a `///` comment
  giving its source and the date it was checked. Nothing hardcoded anywhere else.
- If you do not know a real figure — a barème, a tax rate, a fee schedule, an IRL value — say so and
  leave a clearly named placeholder. Do not invent plausible-looking French tax numbers.
- TAEG and taux nominal are different things. Distinguish them explicitly wherever both appear.

## Error handling and tests

- `thiserror` for typed errors in `immo-core`; `anyhow` only at the `immo-web` boundary.
- No `unwrap()`, `expect()`, or `panic!()` outside tests and `main`.
- Every `core` function producing a number the user sees has a known-answer test, with the worked
  example stated in the test name or a comment above it.
- Test the amortisation schedule against hand-checked values, never against the implementation's
  own output.

## Working with me

I know traits, `Result`, and the borrow checker. I do not know the ecosystem well, and learning it
is half the point of this project.

- When you use a non-obvious idiom — extractors, `Layer`, lifetimes on a struct, `impl Trait` in
  return position — explain why in one or two sentences, in chat rather than as a code comment.
- If my request implies an unidiomatic design, say so before implementing it.
- Prefer the simple version over the clever one, and tell me when you deliberately chose the
  simple one.

## Do not

- Add a dependency without asking first, including small ones.
- Introduce npm, a bundler, TypeScript, or a frontend framework.
- Write financial logic in `crates/immo-web`.
- Leave commented-out code, or comments that restate what the code does.
- Reformat or restructure files you were not asked to touch.