|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Human Essentials is a Ruby on Rails inventory management system for diaper banks and essentials banks. It's a Ruby for Good project serving 200+ non-profit organizations. The app manages donations, purchases, distributions, inventory, partners, and requests for essential items. |
| 8 | + |
| 9 | +## Common Commands |
| 10 | + |
| 11 | +### Development |
| 12 | +```bash |
| 13 | +bin/setup # First-time setup (installs gems, creates DB, seeds) |
| 14 | +bin/start # Starts Rails server (port 3000) + Delayed Job worker |
| 15 | +``` |
| 16 | + |
| 17 | +### Testing |
| 18 | +```bash |
| 19 | +bundle exec rspec # Run full test suite |
| 20 | +bundle exec rspec spec/models/item_spec.rb # Run a single test file |
| 21 | +bundle exec rspec spec/models/item_spec.rb:42 # Run a single test at line |
| 22 | +bundle exec rspec spec/models/ # Run a directory of tests |
| 23 | +``` |
| 24 | + |
| 25 | +CI splits tests into two workflows: `rspec` (unit tests, excludes system/request specs) and `rspec-system` (system and request specs only, 6 parallel nodes). System tests use Capybara with Cuprite (headless Chrome). |
| 26 | + |
| 27 | +### Linting |
| 28 | +```bash |
| 29 | +bundle exec rubocop # Ruby linter (Standard-based config) |
| 30 | +bundle exec erb_lint --lint-all # ERB template linter |
| 31 | +bundle exec brakeman # Security scanner |
| 32 | +``` |
| 33 | + |
| 34 | +### Database |
| 35 | +```bash |
| 36 | +bundle exec rake db:migrate |
| 37 | +bundle exec rake db:seed |
| 38 | +bundle exec rake db:reset # Drop + create + migrate + seed |
| 39 | +``` |
| 40 | + |
| 41 | +## Architecture |
| 42 | + |
| 43 | +### Multi-Tenancy |
| 44 | +Nearly all data is scoped to an `Organization`. Most models `belong_to :organization` and queries should always scope by organization context. The current user's organization is the primary tenant boundary. |
| 45 | + |
| 46 | +### Roles (Rolify) |
| 47 | +Four roles defined in `Role`: `ORG_USER`, `ORG_ADMIN`, `SUPER_ADMIN`, `PARTNER`. Roles are polymorphic and scoped to a resource (usually an Organization). Authentication is via Devise. |
| 48 | + |
| 49 | +### Event Sourcing for Inventory |
| 50 | +Inventory is **not** tracked via simple column updates. Instead, it uses an event sourcing pattern: |
| 51 | + |
| 52 | +- **`Event`** (STI base model) stores all inventory-affecting actions as JSONB events |
| 53 | +- Subclasses: `DonationEvent`, `DistributionEvent`, `PurchaseEvent`, `TransferEvent`, `AdjustmentEvent`, `AuditEvent`, `KitAllocateEvent`, `SnapshotEvent`, etc. |
| 54 | +- **`InventoryAggregate`** replays events to compute current inventory state. It finds the most recent `SnapshotEvent` and replays subsequent events |
| 55 | +- **`EventTypes::Inventory`** is the in-memory inventory representation built from events |
| 56 | +- When creating/updating donations, distributions, purchases, transfers, or adjustments, the corresponding service creates an Event, and `Event#validate_inventory` replays all events to verify consistency |
| 57 | + |
| 58 | +This means: to check inventory levels, use `InventoryAggregate.inventory_for(organization_id)`, not direct DB queries on quantity columns. |
| 59 | + |
| 60 | +### Service Objects |
| 61 | +Business logic lives in service classes (`app/services/`), not controllers. Pattern: `{Model}{Action}Service` (e.g., `DistributionCreateService`, `DonationDestroyService`). Controllers are thin and delegate to services. |
| 62 | + |
| 63 | +### Key Models |
| 64 | +- **Item**: Individual item types (diapers, wipes, etc.) belonging to an Organization. Maps to a `BaseItem` (system-wide template) via `partner_key`. |
| 65 | +- **Kit**: A bundle of items. Kits contain line items referencing Items. |
| 66 | +- **StorageLocation**: Where inventory is physically stored. Inventory quantities are per storage location. |
| 67 | +- **Distribution**: Items sent to a Partner. **Donation/Purchase**: Items coming in. **Transfer**: Items between storage locations. **Adjustment**: Manual inventory corrections. |
| 68 | +- **Partner**: Organizations that receive distributions. Partners have their own portal (`/partners/*` routes) and users. |
| 69 | +- **Request**: Partner requests for items, which can become Distributions. |
| 70 | + |
| 71 | +### Routes Structure |
| 72 | +- `/` - Bank user dashboard and resources (distributions, donations, etc.) |
| 73 | +- `/partners/*` - Partner-facing portal (separate namespace) |
| 74 | +- `/admin/*` - Super admin management |
| 75 | +- `/reports/*` - Reporting endpoints |
| 76 | + |
| 77 | +### Query Objects |
| 78 | +Complex queries are extracted into `app/queries/` (e.g., `ItemsInQuery`, `LowInventoryQuery`). |
| 79 | + |
| 80 | +### Frontend |
| 81 | +Bootstrap 5.2, Turbo Rails, Stimulus.js, ImportMap (no Webpack/bundler). JavaScript controllers live in `app/javascript/`. |
| 82 | + |
| 83 | +### Background Jobs |
| 84 | +Delayed Job for async processing (emails, etc.). Clockwork (`clock.rb`) for scheduled tasks (caching historical data, reminder emails, DB backups). |
| 85 | + |
| 86 | +### Feature Flags |
| 87 | +Flipper is available for feature flags, accessible at `/flipper` (auth required). |
| 88 | + |
| 89 | +## Testing Conventions |
| 90 | + |
| 91 | +- RSpec with FactoryBot. Factories are in `spec/factories/`. |
| 92 | +- **Setting up inventory in tests**: Use `TestInventory.create_inventory(organization, { storage_location_id => [[item_id, quantity], ...] })` from `spec/inventory.rb`. There's also a `setup_storage_location` helper in `spec/support/inventory_assistant.rb`. |
| 93 | +- System tests use Capybara with Cuprite driver. Failed screenshots go to `tmp/screenshots/` and `tmp/capybara/`. |
| 94 | +- Models use `has_paper_trail` for audit trails and `Discard` for soft deletes (not `destroy`). |
| 95 | +- The `Filterable` concern provides `class_filter` for scope-based filtering on index actions. |
| 96 | + |
| 97 | +## Dev Credentials |
| 98 | + |
| 99 | +All passwords are `password!`. Key accounts: `superadmin@example.com`, `org_admin1@example.com`, `user_1@example.com`. |
0 commit comments