# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Fixin.me is a "quantified self" Rails 7.2.3 application for personal data tracking. Users define hierarchical **quantities** (metrics to track), **units** (with optional conversion hierarchies), and **readouts** (individual measurements). There is also a non-persistent **measurement** model used as a form wrapper.

## Setup

Configuration files are distributed as `.dist` templates — copy and customize before use:

```bash
cp config/application.rb.dist config/application.rb
cp config/database.yml.dist config/database.yml
cp config/puma.rb.dist config/puma.rb
```

```bash
bundle config --local frozen true
bundle config --local path .gem
bundle config --local with mysql development test   # or: pg, sqlite
bundle install
RAILS_ENV=development bundle exec rails db:create db:migrate db:seed
```

## Common Commands

```bash
bundle exec rails s                                          # start server
bundle exec rails test                                       # all unit/model/controller tests
bundle exec rails test:system                                # all system tests (Capybara + Selenium)
bundle exec rails test test/system/units_test.rb            # single test file
bundle exec rails test --seed 64690 --name test_add_unit    # single test by name
bundle exec rails db:seed:export                             # export default settings as seed file
```

## Architecture

### Data Model

- **Quantity** — hierarchical tree (self-referential `parent_id`). Cached `depth` and `pathname` fields are recomputed via recursive CTEs on write. Direct assignment to cached fields is blocked.
- **Unit** — optional hierarchy via `base_id` and `multiplier` for unit conversion. Multiplier precision/scale is validated by a custom validator.
- **Readout** — single measurement: `value` (IEEE 754 float), `quantity`, `unit`, `category`.
- **Measurement** — `ActiveModel::Model` form wrapper (not database-backed); bridges the readout creation form.
- **User** — Devise-managed with a status enum: `admin`, `active`, `restricted`, `locked`, `disabled`. Admins can disguise as other users.

### Hierarchical Queries

Both `Quantity` and `Unit` use recursive CTEs for tree traversal (ordered traversal, ancestors, progenies, common ancestors). `lib/core_ext/arel/` patches Arel to support CTE with `UPDATE`/`DELETE` statements, working around Rails issue #54658.

### Custom Extensions (`lib/core_ext/`)

- **arel/** — CTE support for UPDATE/DELETE
- **active_model/** — precision/scale validator used by `Unit#multiplier`
- **active_record/** — `attr_cached` mechanism (see `ApplicationRecord`)
- **action_view/** — record identifier suffixes
- Miscellaneous: `Array#delete_bang`, `BigDecimal` scientific notation

### Response Handling

Controllers respond to both HTML and Turbo Stream formats. Errors during Turbo Stream requests trigger a redirect with flash rather than rendering inline, handled in `ApplicationController`.

### Numeric Precision

Readout values are stored as IEEE 754 double-precision floats (not fixed-point decimals). Rationale in `DESIGN.md`: biological values span many orders of magnitude; 15-digit float precision is sufficient and avoids conversion overhead.

### Routes

```
measurements   GET/POST /measurements
readouts       GET/POST /readouts, DELETE /readouts/:id/discard
quantities     CRUD + POST /quantities/:id/reparent
units          CRUD + POST /units/:id/rebase
users          CRUD + POST /users/:id/disguise, POST /users/revert
default/       namespace for default units import/export and admin panel
root           → /units (authenticated), /sign_in (unauthenticated)
```

## Database Requirements

The database must support:
- Recursive CTEs with `UPDATE`/`DELETE` (MySQL ≥ 8.0, PostgreSQL, or SQLite3)
- Decimal precision of 30+ digits