fixin.me/CLAUDE.md

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:

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

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

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