Altocumulus

English | 日本語

A clinical ledger application for a single hospital department, tracking patients, diagnoses, surgeries, and hospitalizations. It brings outpatient and ward records together in one place, with a focus on making elective slot utilization, the lifecycle of a hospitalization from request to discharge, and an audit log of every change visible under per-user permissions. The landing page is an operations calendar spanning 50 days by default, showing daily surgery and admission counts, congestion warnings, holidays, and announcements at a glance.

It is built entirely on the stock Rails 8.1 stack (Propshaft + importmap + Turbo/Stimulus) — no Node build pipeline and no external database server.

Table of contents

• Features
• Tech stack
• Setup
• Configuration
• Development commands and testing
• Domain model
• Design notes
• Deployment
• Development rules
• License

Features

Master data is edited by administrators only. Diagnoses, surgery procedures, holidays (closed days / day notes / slot overrides), elective slot rules, departments, surgery locations, surgical devices, teams and team terms can be viewed by every signed-in user, but creating, editing and deleting them (and the "new" buttons) require the admin role; others are redirected with a "not authorized" notice. The one exception is data entry: any signed-in user may register a new diagnosis or surgery procedure from inside a picker modal (a turbo-frame request) while booking a hospitalization or surgery.

Reservation form. The calendar books through one form object (Reservation) that saves a hospitalization and, for the purpose "surgery", its surgery in a single transaction, with live previews of the patient, admission counts, slot usage and team members next to the form. Details are under Reservation form in the design notes.

Authentication, user management, role separation (user / data manager / admin), access logging, and idle timeout are implemented. Every application screen requires a logged-in user; the exceptions are /login, the language switcher (PATCH /locale), and the /up health check.

Tech stack

Setup

Prerequisites: Ruby 4.0.7 (see .ruby-version) and Bundler.

git clone https://github.com/studiome/altocumulus.git
cd altocumulus
bin/setup

bin/setup installs gems, creates/migrates/seeds the database, clears logs, and then starts the development server. To prepare everything without starting the server:

bin/setup --skip-server

After that, use bin/dev (via Procfile.dev it runs the Rails server and the Tailwind watcher together).

bin/dev

The app is available at http://localhost:3000. The root path is the operations calendar (OperationsCalendarController#index); unauthenticated visitors are redirected to the login screen.

In development, bin/setup also runs the seeds, so you can log in with the following demo account (see db/seeds.rb), which holds both the admin and data_manager roles. The sign-in screen is shown in Japanese for visitors who have not signed in; switch the language on the sign-in page itself, or after logging in from the Account page (/account).

The seeds contain only this account and the masters. To fill a development database with fictional patients, hospitalizations and surgeries for UI review, run bin/rails dev:demo_data (see Development commands and testing and Development demo data).

For production, the first administrator and the other runtime settings are configured through environment variables and a site configuration file; see Configuration.

Configuration

Environment variables

Runtime behavior is tuned with environment variables (config/application.rb, db/seeds.rb).

Setting both BOOTSTRAP_ADMIN_LOGIN_ID and BOOTSTRAP_ADMIN_PASSWORD on first boot creates a bootstrap administrator account (named Administrator) when db:seed runs. If a user with the same login id already exists, nothing happens. BOOTSTRAP_ADMIN_EMAIL is kept as an older name for BOOTSTRAP_ADMIN_LOGIN_ID: it is still read as a fallback when that is unset. With Kamal these variables must be listed under env: in config/deploy.yml -- see Before the first deploy.

Site configuration

Per-hospital customizations are not hardcoded; they live in a YAML file loaded once at boot by SiteConfig (app/models/site_config.rb). The file is the one at SITE_CONFIG_PATH if that environment variable is set (in production, mount it with a Kamal volume -- see the commented example in config/deploy.yml), otherwise the committed config/site.yml, a neutral default that keeps the stock behavior. config/site.example.yml shows every key filled in. A malformed file, an unknown key or an unknown field name stops the boot with a SiteConfig::Error. (Field names are not checked while migrations are pending, so db:prepare can boot and migrate first; the server's boot afterwards checks them.)

Keys:

• features.teams (default false): turns the care-team feature on (see Teams). While false, the Teams screens, the team selects and the team displays are hidden and team_id may not be listed under required_fields (the boot fails if it is).
• required_fields.hospitalization / required_fields.surgery: attribute names that must be filled in before saving. The red asterisk on the form follows the same list (Model.required_attribute?).
• required_fields.hospitalization_by_purpose: the same, but only for hospitalizations of one purpose (surgery, examination, chemotherapy, chemoradiotherapy, other), e.g. examination: [scheduled_procedure_date, procedure_name]. The asterisk follows the purpose chosen in the form (Hospitalization.required_attribute?(attr, record) or (attr, purpose: ...)). The reservation doctor is the user reference reservation_doctor_id (not the old reservation_doctor string).
• patient.hospital_id_format / patient.hospital_id_format_hint: a regular expression the patient's hospital ID must match when it is set or changed, and a human-readable description for the error message. Omit for no restriction.
• masters.departments / masters.surgery_locations / masters.surgical_devices: lists of names (for example a hospital's departments, its rooms such as a hybrid room or cath lab, and its support devices) to make sure exist in the master tables. Nothing hospital-specific is hardcoded in the app; the vocabulary lives in those admin-editable masters (Masters menu), and this key only seeds them. Run bin/rails site:seed_masters after a deploy (it is also part of db:seed): it only creates missing names, in the listed order after the existing rows, and never renames, reorders or deletes anything. A deactivated master is no longer offered for new selections but still shows on the surgeries that use it; a master in use cannot be deleted. A surgery_locations entry may also be a mapping, {name: ..., asks_performing_department: true}, which flags a place whose cases may be performed by another department (a hint for the surgery form; set only on newly created rows, and editable on the Surgery Locations master screen). Special slot lane counts are not part of this file; they are edited on the master screens.
• masters.teams: team names (or {name: ..., color: blue}, color one of blue/red/green/orange/purple/ teal/gray), seeded the same additive way as the other masters. Terms and members are entered in the app, not in this file.
• ledger_columns.operations_calendar / weekly_pdf / examination_calendar: the columns each ledger table shows, in order (the calendar's and PDF's day cell is always first and not listed). Columns come from the ledger column registry (LedgerColumn, app/models/ledger_column.rb and app/models/ledger_columns/): surgery ledgers use time_slot, admission_dates, patient, age_sex, diagnosis_procedure, operator_assistant, duration_anesthesia, team (needs features.teams), category, reservation, referral_adl, status; the examination ledger uses admission_dates, patient, age_sex, diagnosis_procedure_name, purpose, team, category, reservation, referral_adl, status. Omit a ledger for its built-in default. Unknown or duplicate columns, an empty list, or team without features.teams stop the boot. See config/site.yml for the column meanings.
• weekly_pdf: font_size (6-10, default 8) and title (replaces the translated PDF title; keep site-specific wording here, not in code). Columns have a preferred and a minimum width in the registry: spare page width is shared out by each column's flex weight (category 3, team 2, diagnosis/procedure 2, referral/ADL 1.5, patient, reservation and status 1; others 0), not by width, so the columns that wrap most grow most; a too wide set shrinks towards the minimums, and only then does the font step down (8 -> 7.5 -> 7 -> 6.5) before a final proportional squeeze (LedgerColumnFitting).
• exports: named CSV exports for the clerk's admission list / registry (NCD) lists. Each entry is <name>: {subject: surgery|hospitalization, fields: [...], label: optional}; fields come from the export field registry (ExportField, app/models/export_field.rb and app/models/export_fields/), which yields one plain value per column (unlike the stacked ledger cells). Omit the key for the built-in surgery_list and admission_list (every field of the subject); exports: {} switches exports off. Unknown subjects/fields, duplicates, an empty list, a bad name or team/team_members without features.teams stop the boot. See config/site.yml for every field and config/site.example.yml for an ncd_list.

In tests, with_site_config(hash) { ... } swaps the config temporarily.

Development commands and testing

bin/dev                                        # dev server + Tailwind watcher
bin/rails test                                 # all tests except system tests
bin/rails test test/models/patient_test.rb     # a single file
bin/rails test test/models/patient_test.rb:12  # a single test at a line
bin/rails test:system                          # system tests (requires Selenium)
bin/rails db:prepare                           # create / migrate / seed the database
bin/rubocop                                    # lint
bin/brakeman                                   # static security analysis
bin/bundler-audit                              # audit gems for known vulnerabilities
bin/ci                                         # the same checks CI runs (config/ci.rb)

bin/ci runs setup → RuboCop → the gem/importmap/Brakeman audits → tests → a re-run of the seeds. GitHub Actions (.github/workflows/ci.yml) runs an equivalent job on pushes to main and on pull requests.

Rake tasks (lib/tasks/):