Guava Docs

domain

• ACGME Call Requirements Summary - Guava Docs

  ACGME Call Requirements Summary

  Extracted from external_docs/acgme-common-program-requirements-residency-2025.pdf (Section 6: The Learning and Working Environment, effective September 3, 2025).

  ---

  80-Hour Weekly Max (6.20)

  • 80 hours/week averaged over 4 weeks, including all in-house clinical/educational activities, clinical work from home, and moonlighting (Core)

  Rest Between Shifts (6.21)

  • 8 hours off between scheduled clinical work and education periods (Detail — “should”)
  • 14 hours off mandatory after 24 hours of in-house call (Core)

  Day Off (6.21.b)

  • 1 day in 7 free of all clinical work and education, averaged over 4 weeks (Core)
  • At-home call cannot be assigned on these free days
  • A “day off” is defined as one continuous 24-hour period free from all administrative, clinical, and educational activities

  Maximum Continuous Duty (6.22)

  • 24 hours max of continuous scheduled clinical assignments (Core)
  • +4 hours allowed only for transitions of care / education — no new patient care responsibilities (Core)

  In-House Night Float (6.26)

  • Must comply with 80-hour and 1-day-in-7 rules (Core)
  • Max consecutive weeks and months/year left to specialty Review Committees

  In-House Call Frequency (6.27)

  • No more than every 3rd night (Q3), averaged over 4 weeks (Core)

  At-Home Call (6.28)

  • Patient care time counts toward the 80-hour limit (Core)
  • Not subject to the every-third-night rule
  • Must satisfy the 1-day-in-7 requirement
  • Must not be so frequent as to preclude rest or reasonable personal time (Core)
  • Counted activities: phone calls, documentation, EHR notes
  • Not counted: reading about next day’s case, studying, research

  Moonlighting (6.25)

  • Counts toward 80-hour limit (Core)
  • PGY-1 residents cannot moonlight (Core)

  Exceptions (6.24)

  • Review Committees may grant up to 88 hours/week for specific rotations with sound educational rationale
  • DIO/GMEC approval required before request goes to Review Committee

  ---

  Specialty-Specific Variations (from Review Committees, not Common Requirements)

  Emergency Medicine

  • Maximum 12 hours continuous duty in the ED
  • Maximum 60 scheduled clinical hours/week in ED
  • Minimum rest between ED shifts = shift length (12h shift → 12h rest)
  • 1 day in 7 cannot be averaged — must occur each week
  • 88-hour exceptions categorically denied

  Internal Medicine

  • Call frequency (Q3) cannot be averaged — strict every-third-night maximum

  Surgery / Surgical Subspecialties

  • May have program-specific exceptions for complex cases
  • Neurological Surgery is the only specialty routinely granted 88-hour exceptions
• Call Scheduling Domain Model Proposal - Guava Docs

  Call Scheduling Domain Model Proposal

  Design Philosophy

  This model captures the core structures needed for residency call scheduling without prematurely encoding compliance rules, eligibility logic, or fairness tracking. The guiding principles:

  • One shift = one person. A shift is the atomic unit of work. If two residents are needed at the same time (e.g., a primary and a senior), those are two separate shifts connected by a relationship.
  • Templates define patterns, shifts are instances. Programs describe recurring structures (“weeknight call is 6pm–7am”), and the system generates concrete shifts for specific dates.
  • Relationships encode structure. Rather than baking supervision, backup, or handoff semantics into the shift itself, a generic relationship table lets programs define whatever associations matter to them.
  • No pools. Eligibility for call is derived from rotation assignments, not maintained as a separate membership concept. This avoids redundancy with your existing rotation model.
  • Configuration over code. Call types, sites, templates, and relationships are all data, allowing different programs (psychiatry, internal medicine, surgery) to model their call structures without schema changes.

  ---

  Entities

  programs

  Already exists in your schema. Call scheduling entities are scoped to a program.

  ---

  sites

  A physical location where call happens. Programs may train residents across multiple hospitals, each with different call structures. A site belongs to a single program.

  sites ├── id TEXT PRIMARY KEY ├── program_id TEXT NOT NULL → programs(id) ├── name TEXT NOT NULL -- "University Hospital", "VA Medical Center" ├── code TEXT NOT NULL -- "UH", "VA" (short identifier) ├── created_at TIMESTAMPTZ └── updated_at TIMESTAMPTZ UNIQUE(program_id, name) UNIQUE(program_id, code)

  Why it exists: Different sites have different call structures. University Hospital might have 24/7 in-house psychiatry call while the VA has home call only. Templates are site-scoped, so the same program can have completely different shift patterns at each site.

  How it’s used: When an admin creates call shift templates, they select a site. When viewing the call schedule, shifts can be filtered by site.

  ---

  call_types

  A program-defined label describing the format or structure of a call shift. These are the categories that are meaningful within a specific program’s culture and workflow.

  call_types ├── id TEXT PRIMARY KEY ├── program_id TEXT NOT NULL → programs(id) ├── name TEXT NOT NULL -- "Night Float", "Long Call", "Short Call" ├── description TEXT ├── color TEXT DEFAULT '#6366f1' ├── created_at TIMESTAMPTZ └── updated_at TIMESTAMPTZ UNIQUE(program_id, name)

  Why it exists: Programs use different call structures and need their own vocabulary. A psychiatry program might have “Short Call” (5pm–10pm) and “Long Call” (Saturday 8am–8pm) while an internal medicine program has “Night Float” and “Jeopardy.” These labels are used for display, filtering, and eventually for equity tracking (“how many Night Float shifts has each resident worked?”).

  What it is NOT: This is not where time windows are defined (that’s on the template). This is not where in-house vs. home-call is determined (deferred). Multiple templates can share the same call type — e.g., “Night Float at University Hospital” and “Night Float at VA” are different templates with the same call type.

  Example values:

  Program	Call Types
  Psychiatry	Short Call, Long Call, Weekend Call
  Internal Medicine	Night Float, Jeopardy, ICU Night
  Surgery	In-House Call, Trauma Call, Backup

  ---

  call_schedules

  A versionable workspace representing a scheduling period — the place where an admin defines call structure, generates shifts, and manages assignments. Analogous to your existing rotation_schedules for rotations.

  call_schedules ├── id TEXT PRIMARY KEY ├── program_id TEXT NOT NULL → programs(id) ├── name TEXT NOT NULL -- "2025-2026 Academic Year", "July-Dec 2025" ├── start_date DATE NOT NULL ├── end_date DATE NOT NULL ├── created_at TIMESTAMPTZ └── updated_at TIMESTAMPTZ CHECK(start_date <= end_date) UNIQUE(program_id, name)

  Why it exists: Programs build call schedules for defined periods (academic year, quarter, month). This container groups all the templates, shifts, and assignments for that period. An admin might have a draft schedule for next quarter while the current quarter is still active.

  Scope: A call schedule is program-wide, not site-specific. A single schedule can contain templates and shifts across multiple sites. This mirrors how a program director thinks: “I need to build the call schedule for next year” — which includes all sites.

  Copy-forward workflow: Call structures tend to be similar year over year, with minor adjustments. Rather than rebuilding from scratch, an admin copies a previous schedule’s templates and relationships into a new schedule, tweaks what changed, and regenerates shifts. Specifically:

  • Copied: call_shift_templates and call_shift_template_relationships (the structure)
  • Not copied: call_shifts and call_assignments (the instances — these are generated fresh for the new date range)

  This gives the admin a starting point that reflects last year’s patterns while keeping each schedule fully independent. Modifying a copied template doesn’t affect the source schedule, and last year’s schedule is preserved as a historical record.

  ---

  call_shift_templates

  A recurring pattern that describes a type of shift that happens repeatedly. Templates capture the “shape” of a shift — when it starts, when it ends, which days it applies to, and at which site.

  call_shift_templates ├── id TEXT PRIMARY KEY ├── call_schedule_id TEXT NOT NULL → call_schedules(id) ├── site_id TEXT NOT NULL → sites(id) ├── call_type_id TEXT NOT NULL → call_types(id) ├── name TEXT NOT NULL -- "Weeknight Primary", "Weekend Senior" ├── start_time TIME NOT NULL -- 18:00 ├── end_time TIME NOT NULL -- 07:00 ├── spans_midnight BOOLEAN DEFAULT FALSE ├── applicable_days INT[] -- ISO weekdays: {1,2,3,4,5} = Mon-Fri ├── is_active BOOLEAN DEFAULT TRUE ├── created_at TIMESTAMPTZ └── updated_at TIMESTAMPTZ UNIQUE(call_schedule_id, name)

  Why it exists: Without templates, an admin would need to manually create hundreds of individual shifts for a year-long schedule. Templates let them define the pattern once and generate shifts in bulk.

  Key fields explained:

  • start_time / end_time / spans_midnight: Defines the time window in the program’s local timezone (from programs.timezone). A night float shift might be start_time=19:00, end_time=07:00, spans_midnight=true. A short call might be start_time=17:00, end_time=22:00, spans_midnight=false.

  • applicable_days: ISO weekday numbers (1=Monday through 7=Sunday). Controls which days of the week this template generates shifts for. {1,2,3,4} means Monday through Thursday. {6,7} means weekends. NULL means the template exists but shifts are created manually (useful for holidays or irregular patterns).

  • is_active: Soft toggle. Deactivating a template stops future generation but doesn’t remove existing shifts.

  Example: Psychiatry program at a single site

  Template Name	Type	Start	End	Spans Midnight	Days
  Weeknight Short Call	Short Call	17:00	22:00	No	Mon–Fri
  Weekend Day Call	Long Call	08:00	20:00	No	Sat, Sun
  Weekend Night Call	Long Call	20:00	08:00	Yes	Sat, Sun

  Example: Internal medicine program, multi-site

  Template Name	Site	Type	Start	End	Days
  Ward Night Float	University Hospital	Night Float	19:00	07:00	Mon–Fri
  ICU Night	University Hospital	ICU Night	19:00	07:00	Every day
  Ward Night Float	VA	Night Float	19:00	07:00	Mon–Fri
  Weekend Jeopardy	University Hospital	Jeopardy	07:00	07:00	Sat, Sun

  ---

  call_shift_template_relationships

  Defines structural relationships between two templates. This is how programs encode that one shift role supervises another, that one shift serves as backup for another, or that two shifts work as a pair.

  call_shift_template_relationships ├── id TEXT PRIMARY KEY ├── template_a_id TEXT NOT NULL → call_shift_templates(id) ├── template_b_id TEXT NOT NULL → call_shift_templates(id) ├── relationship_type TEXT NOT NULL ├── created_at TIMESTAMPTZ UNIQUE(template_a_id, template_b_id, relationship_type) CHECK(template_a_id != template_b_id)

  Why it exists: Many call structures involve multiple residents working together with defined roles. Rather than encoding these roles into the shift itself (which is inflexible), relationships between shifts let programs define whatever structure they need.

  Relationship semantics: The relationship is directional — “A [relationship_type] B” — with a convention that A is the actor:

  relationship_type	Meaning	Example
  supervises	A oversees B	Senior resident supervises intern on call
  backs_up	A is backup for B	Jeopardy resident backs up night float
  relieves	A takes over from B	Night float relieves day team
  pairs_with	A and B work together, no hierarchy	Two interns splitting weekend coverage

  Example: Psychiatry tandem call

  The psychiatry program has PGY-2+ seniors supervising PGY-1 interns during weekend call:

  Template: "Weekend Primary" (PGY-1 level) Template: "Weekend Senior" (PGY-2+ level) Relationship: Weekend Senior → supervises → Weekend Primary

  Example: Internal medicine jeopardy

  Template: "Ward Night Float" Template: "Weekend Jeopardy" Relationship: Weekend Jeopardy → backs_up → Ward Night Float

  When instances are generated, these template relationships are propagated to the corresponding shift instances via call_shift_relationships.

  ---

  call_shifts

  A concrete shift on a specific date and time that needs one resident assigned. Generated from templates or created manually for one-off situations.

  call_shifts ├── id TEXT PRIMARY KEY ├── call_schedule_id TEXT NOT NULL → call_schedules(id) ├── template_id TEXT → call_shift_templates(id) -- nullable ├── site_id TEXT NOT NULL → sites(id) ├── call_type_id TEXT NOT NULL → call_types(id) ├── starts_at TIMESTAMPTZ NOT NULL ├── ends_at TIMESTAMPTZ NOT NULL ├── notes TEXT ├── created_at TIMESTAMPTZ └── updated_at TIMESTAMPTZ CHECK(starts_at < ends_at) UNIQUE(template_id, starts_at) -- prevents duplicate generation

  Why it exists: This is the core operational entity — the thing that gets assigned to a resident and shows up on the calendar.

  Template-generated vs. manual:

  • Template-generated: template_id is set. Fields like site_id, call_type_id, starts_at, ends_at are computed from the template + target date. The UNIQUE(template_id, starts_at) constraint prevents generating the same shift twice.

  • Manual (one-off): template_id is NULL. The admin creates a shift directly for an unusual situation — holiday coverage, emergency staffing, a shift that doesn’t fit any template pattern. All fields are set explicitly.

  Why site_id and call_type_id are denormalized from the template: Shifts need to be queryable by site and type without joining through templates. A manually-created shift (no template) still needs these fields. And if a template is deactivated or modified, existing shifts should retain their original values.

  Time representation: starts_at and ends_at are stored as TIMESTAMPTZ. The application converts from the program’s timezone (stored on programs.timezone) when generating from templates. This handles DST transitions correctly and allows cross-timezone queries.

  ---

  call_shift_relationships

  Instance-level relationships between specific shifts on specific dates. Typically auto-generated from template relationships when shifts are created, but can also be created manually.

  call_shift_relationships ├── id TEXT PRIMARY KEY ├── shift_a_id TEXT NOT NULL → call_shifts(id) ├── shift_b_id TEXT NOT NULL → call_shifts(id) ├── relationship_type TEXT NOT NULL ├── source_template_relationship_id TEXT → call_shift_template_relationships(id) -- nullable ├── created_at TIMESTAMPTZ UNIQUE(shift_a_id, shift_b_id, relationship_type) CHECK(shift_a_id != shift_b_id)

  Why it exists separately from template relationships: Template relationships say “these patterns are related.” Instance relationships say “these specific shifts on January 15th are related.” This is needed because:

  1. Not every template-generated shift will have a corresponding partner (one might be cancelled).
  2. Manual shifts can participate in relationships too.
  3. The relationship is the thing that connects “Dr. Smith is supervising Dr. Jones tonight” — you need the concrete instances.

  source_template_relationship_id: Traces back to the template relationship that caused this instance relationship to be created. NULL for manually-created relationships. Set to NULL (via ON DELETE SET NULL) if the source template relationship is deleted — the instance relationship survives independently.

  ---

  call_assignments

  The assignment of one resident to one shift.

  call_assignments ├── id TEXT PRIMARY KEY ├── call_shift_id TEXT NOT NULL → call_shifts(id) ├── resident_id TEXT NOT NULL → residents(id) ├── assigned_at TIMESTAMPTZ DEFAULT NOW() ├── created_at TIMESTAMPTZ └── updated_at TIMESTAMPTZ UNIQUE(call_shift_id) -- one person per shift

  Why it exists as a separate table (not a column on call_shifts): Separating assignments from shifts makes it easy to:

  • Query unfilled shifts (LEFT JOIN call_assignments WHERE assignment IS NULL)
  • Track assignment history (who was previously assigned before a swap)
  • Add assignment metadata later (swap tracking, approval workflows)

  The UNIQUE(call_shift_id) constraint enforces the one-shift-one-person invariant at the database level.

  ---

  Deferred Concepts

  These were discussed but intentionally excluded from v1. The schema is designed so they can be added without restructuring existing tables.

  Concept	What it would add	How to add later
  Call services	Service-level granularity (ICU vs. Wards) for eligibility	Add call_services table, optional FK on templates and shifts
  PGY eligibility	pgy_min/pgy_max on templates and shifts	Add columns to call_shift_templates and call_shifts
  ACGME compliance	Duty hour tracking, violation detection	Add compliance rule tables, duty hour logs
  Fairness tracking	Equity ledgers, weekend/holiday counts	Add equity tracking tables, reporting views
  Call model (in-house vs. home)	Affects ACGME hour calculations	Add model enum to call_types
  Shift status	open/filled/cancelled lifecycle	Add status column to call_shifts (or derive from assignments)
  Required/optional shifts	Whether a shift must be filled	Add is_required to templates and shifts
  Assigned-by audit	Who made the assignment	Add assigned_by FK to call_assignments
  Holidays	Holiday flagging, equity weighting	Add holidays table, is_holiday/holiday_id on shifts
  Unavailability	Vacation, leave, conference blocking	Add unavailability table, check during assignment

  ---

  Generation Flow

  The expected workflow for building a call schedule:

  1. Admin creates a call_schedule for a date range 2. Admin creates call_shift_templates defining recurring patterns 3. Admin creates call_shift_template_relationships between templates 4. System generates call_shifts from templates for each applicable date 5. System generates call_shift_relationships from template relationships 6. Admin (or solver) creates call_assignments for each shift

  Generation logic (step 4):

  For each template where applicable_days is not null: - Iterate through each date in the call_schedule’s date range - If the date’s ISO weekday is in applicable_days - Compute starts_at = date + template.start_time (in program timezone), converted to UTC - Compute ends_at = date + template.end_time (+ 1 day if spans_midnight), converted to UTC - Insert a call_shift linked to this template

  Relationship propagation (step 5):

  For each template relationship (A relates-to B): - Find pairs of generated shifts where shift_a.template_id = A and shift_b.template_id = B - Match by date (or overlapping time window) - Insert a call_shift_relationship with the same type, referencing the template relationship as source

• Medical Resident Call Scheduling - Guava Docs

  Medical Resident Call Scheduling

  Domain Reference Guide

  This document provides foundational domain knowledge for implementing medical resident call scheduling software. It covers terminology, concepts, rules, workflows, and relationships essential for understanding the problem space.

  ---

  1. Core Terminology

  1.1 People & Roles

  Resident A physician in training who has completed medical school and is completing supervised clinical training in a specialty. Residents are both learners and workers—they provide patient care while developing expertise under supervision.

  PGY Level (Post-Graduate Year) The year of residency training, counted from medical school graduation: - PGY-1 (Intern): First year resident. Subject to additional restrictions in some contexts. - PGY-2, PGY-3, etc.: Second year, third year, and so on. - Different specialties have different training lengths (3 years for Internal Medicine, 5+ for Surgery).

  Fellow A physician who has completed residency and is doing additional subspecialty training (e.g., Cardiology fellowship after Internal Medicine residency). Often scheduled similarly to residents.

  Attending (Attending Physician) A fully trained physician who supervises residents and fellows. Not typically scheduled in resident scheduling systems, though they may appear as supervisors.

  Chief Resident A senior resident (often in final year or additional year) with administrative responsibilities including schedule creation, conflict resolution, and peer leadership. Key user of scheduling software.

  Program Coordinator Administrative staff member who manages residency program operations, including schedule maintenance, compliance tracking, and communication. Primary power user of scheduling software.

  Program Director (PD) Faculty physician responsible for the residency program. Approves schedules, monitors compliance, handles escalations. Reviews reports and dashboards rather than building schedules.

  1.2 Time Structures

  Academic Year The training year, typically July 1 through June 30. All scheduling, tracking, and reporting aligns to this cycle. Residents advance PGY levels on July 1.

  Block A fixed period during which residents are assigned to specific rotations. Common block lengths: - 4-week blocks (13 blocks/year) — most common - 2-week blocks (26 blocks/year) - 1-month blocks (12 blocks/year, variable length) - 6-week blocks (less common)

  Programs may use different block lengths for different purposes or PGY levels.

  Rotation A clinical assignment where a resident works in a specific setting, service, or subspecialty for one or more blocks. Examples: - ICU (Intensive Care Unit) - Night Float - Ambulatory/Clinic - Emergency Department - Elective - Research - Vacation

  Rotations define where and what type of work; the schedule defines when and who.

  Service A clinical team or unit that requires staffing. A rotation places a resident on a service. Examples: - “Medicine Team A” - “Cardiology Consults”
  - “MICU” (Medical ICU)

  1.3 Duty Types

  Call Extended duty periods, traditionally overnight, where residents remain available (either in-hospital or from home) to handle patient care needs. “Taking call” means being the responsible resident for a service during off-hours.

  In-House Call (On-Call) Call duty where the resident must remain physically in the hospital. Typically overnight (e.g., 5 PM to 7 AM) but can be 24-hour periods. Counts fully toward duty hour limits.

  Home Call (At-Home Call) Call duty where the resident is available by phone/pager from home and comes to the hospital only if needed. Only time spent on actual patient care activities counts toward the 80-hour limit. Cannot be assigned on required days off.

  Shift A defined work period with specific start and end times. More structured than traditional call. Common in Emergency Medicine and hospitalist models. Examples: - Day shift: 7 AM – 3 PM - Evening shift: 3 PM – 11 PM - Night shift: 11 PM – 7 AM - 12-hour shift: 7 AM – 7 PM

  Night Float A rotation structure where residents work only night shifts for a consecutive period (typically 1-2 weeks), then rotate off. Allows other residents to avoid overnight call during that period.

  Long Call / Short Call Some programs distinguish between: - Long call: Full overnight call (e.g., 24 hours) - Short call: Partial call, often evening only (e.g., until midnight)

  Jeopardy (Backup Call) A designated backup resident who can be called in if the scheduled resident is unable to work (illness, emergency, duty hour violation). Critical for schedule resilience.

  Cross-Cover When a resident covers patients for another team or resident, typically during nights or weekends when primary teams are off.

  1.4 Schedule Types

  Annual Rotation Schedule (Block Schedule, Master Schedule) The year-long assignment of residents to rotations by block. Shows which rotation each resident is on during each block of the year. Created before the academic year begins.

  Example structure:

   Block 1 Block 2 Block 3 Block 4 ... Resident A ICU Wards Clinic Elective Resident B Wards Elective ICU Night Float Resident C Clinic ICU Wards Vacation

  Call Schedule (On-Call Schedule) The specific assignment of residents to call duties within a block or month. More granular than the rotation schedule—shows who is on call each specific day/night.

  Example structure:

  October Call Schedule - Medicine Wards Mon 10/1: Resident A (long call) Tue 10/2: Resident B (long call) Wed 10/3: Resident C (short call) Thu 10/4: Resident A (long call) ...

  Shift Schedule For shift-based rotations (especially Emergency Medicine), the assignment of residents to specific shifts. May include multiple shifts per day requiring coverage.

  Clinic Schedule Assignment of residents to outpatient clinic sessions, often running in parallel with other duties. Residents typically have a “continuity clinic” they attend weekly throughout the year regardless of rotation.

  1.5 Requests & Changes

  Day-Off Request (Time-Off Request) A resident’s request to not be scheduled on specific dates. May be for personal reasons, conferences, interviews, etc. Requests are typically submitted in advance and approved/denied by coordinators or chiefs.

  Swap (Trade) An exchange of assignments between two residents. Both parties must agree, and the swap must not create duty hour violations for either resident. Types: - Direct swap: Resident A takes B’s shift, B takes A’s shift - One-way swap: Resident A takes B’s shift, B owes A a future shift

  Open Shift A shift that needs coverage but has no assigned resident. May result from illness, approved time off, or scheduling gaps. Posted for residents to claim (voluntarily or via jeopardy).

  Coverage When a resident works a shift not originally assigned to them, filling in for another resident or an open shift.

  1.6 Compliance & Tracking

  Duty Hours The total hours a resident spends on clinical and educational activities. Subject to strict limits (see ACGME Rules section). Includes: - All in-hospital clinical time - Clinical work done from home (EHR, phone calls) - Conferences and didactics - Moonlighting

  Violation When a resident’s schedule or logged hours exceed ACGME limits. Violations must be tracked, reported, and addressed. Types include: - Weekly hour violations (>80 hours) - Continuous duty violations (>24+4 hours) - Rest period violations (<8 or <14 hours between shifts) - Day-off violations (<1 day in 7)

  Tally A running count of assignments for fairness tracking. Common tallies: - Total call nights this block/year - Weekend calls - Holiday calls - Specific shift types

  Moonlighting Paid clinical work outside of residency duties. Must be: - Approved by Program Director - Counted toward 80-hour weekly limit - Not permitted for PGY-1 residents

  ---

  2. ACGME Duty Hour Rules

  The Accreditation Council for Graduate Medical Education (ACGME) sets mandatory limits on resident work hours. These rules are non-negotiable—violations can result in loss of program accreditation.

  2.1 Core Rules (Common Program Requirements)

  Rule	Limit	Averaging	Notes
  Weekly hours	80 hours maximum	4-week average	Includes all duty + moonlighting
  Continuous duty	24 hours maximum	Per shift	+4 hours allowed for handoff/education only
  Rest between shifts	8 hours minimum	Per occurrence	“Should” provide 10 hours; 8 is minimum
  Rest after 24h call	14 hours minimum	Per occurrence	Mandatory, no exceptions
  Day off	1 day per 7	4-week average	24 continuous hours free of all duties
  Call frequency	No more than every 3rd night (Q3)	4-week average	In-house call only
  Night float consecutive	6 nights maximum	Per stretch	Must have day off after 6 consecutive nights

  2.2 Rule Details

  80-Hour Weekly Maximum - Calculated as a 4-week rolling total ≤ 320 hours - Includes: clinical work, conferences, moonlighting, clinical work from home - Excludes: reading/studying at home, research on personal time - Programs may request exception up to 88 hours (rarely granted)

  24+4 Continuous Duty - Residents may be scheduled for up to 24 hours continuously - After 24 hours, may remain up to 4 additional hours ONLY for: - Patient care transitions (handoffs) - Educational activities - NO new patient care responsibilities after hour 24 - The +4 hours still count toward 80-hour weekly limit

  Rest Periods - 8 hours minimum between all scheduled work periods (ACGME “must”) - 10 hours recommended between shifts (ACGME “should”) - 14 hours mandatory after 24-hour in-house call - Rest clock starts when resident physically leaves hospital

  Day Off Requirements - One 24-hour period free from ALL duties (clinical, educational, administrative) - Averaged over 4 weeks = minimum 4 days off per 28-day period - At-home call cannot be assigned on required days off - Vacation days do NOT count toward day-off requirements

  Call Frequency (Q3 Rule) - In-house call no more frequent than every third night - Averaged over 4 weeks - Example: Over 28 days, maximum ~9 call nights - Does NOT apply to at-home call

  2.3 Specialty-Specific Variations

  Emergency Medicine (stricter limits) - Maximum 12 hours continuous duty in the ED - Maximum 60 scheduled clinical hours/week in ED - Minimum rest between ED shifts = shift length (12h shift → 12h rest) - 1 day in 7 cannot be averaged—must occur each week - 88-hour exceptions categorically denied

  Internal Medicine - Call frequency (Q3) cannot be averaged—strict every-third-night maximum - No special continuous duty rules beyond Common Requirements

  Surgery / Surgical Subspecialties - May have program-specific exceptions for complex cases - Neurological Surgery only specialty routinely granted 88-hour exceptions

  2.4 Averaging Periods

  All averaged rules must be calculated by rotation, not as a continuous rolling average: - 4-week periods within a rotation - Monthly periods - Rotation length (if shorter than 4 weeks)

  A 12-week rotation would be evaluated as three separate 4-week periods.

  2.5 What Counts Toward Hours

  Counts toward 80-hour limit: - All in-hospital clinical duties - Time on in-house call - Time called into hospital from home call - Clinical work from home (EHR documentation, phone consultations) - Required conferences and didactics - Moonlighting (internal and external) - Administrative duties related to patient care

  Does NOT count: - Reading/studying at home - Research done on personal time (not scheduled research rotation) - Travel time - Brief phone calls during at-home call (at resident discretion)

  ---

  3. Scheduling Concepts

  3.1 The Scheduling Problem

  Resident scheduling is a constraint satisfaction problem with multiple competing objectives:

  Hard Constraints (must satisfy): - ACGME duty hour rules - Minimum staffing requirements per shift/service - Resident eligibility (PGY level, rotation assignment) - Pre-approved time-off requests - Cannot be in two places simultaneously

  Soft Constraints (optimize for): - Fair distribution of undesirable shifts (nights, weekends, holidays) - Resident preferences - Educational balance (exposure to variety) - Continuity of care - Circadian-friendly shift progressions

  3.2 Fairness Metrics

  Call Equity Track and balance the number of call nights per resident. Typically tracked: - Per block/month - Per year - By type (weeknight vs. weekend vs. holiday)

  Weekend Equity Weekend call is considered more burdensome. Track weekend call distribution separately.

  Holiday Equity Major holidays (Thanksgiving, Christmas, New Year’s) tracked separately. Common approach: if you work Thanksgiving, you’re off Christmas.

  Shift Type Balance For shift-based schedules, balance distribution of desirable (day) vs. undesirable (night/evening) shifts.

  3.3 Scheduling Patterns

  Q-Patterns (Call Frequency) - Q2: Every other night (very rare, usually violates rules) - Q3: Every third night (common maximum) - Q4: Every fourth night (common for larger programs) - Q5, Q6, etc.: Less frequent call

  Night Float Model Instead of distributing night call across all residents: 1. Designate one or more residents to work nights for entire block 2. Remaining residents work days with no overnight call 3. Rotate night float assignment across residents over the year

  24+4 Model (Traditional Call) - Resident works normal day, stays overnight, works next morning - Post-call afternoon off - Example: Arrive 6 AM Monday, leave by noon Tuesday

  Shift-Based Model - Discrete shifts (8, 10, or 12 hours) - No 24-hour periods - Common in Emergency Medicine - Requires more transitions but avoids extended duty

  3.4 Scheduling Workflow

  Annual/Block Schedule Creation (months before academic year): 1. Define block dates for academic year 2. Set rotation requirements by PGY level 3. Collect resident preferences/constraints 4. Build rotation assignments ensuring requirements met 5. Review and adjust for conflicts 6. Publish rotation schedule

  Call Schedule Creation (weeks before each block): 1. Identify which residents are eligible (based on rotation assignment) 2. Collect day-off requests 3. Set staffing requirements per day 4. Generate or manually build call assignments 5. Check ACGME compliance 6. Balance tallies for fairness 7. Review and adjust 8. Publish call schedule

  Ongoing Schedule Management: 1. Process swap requests 2. Handle sick calls / emergencies (jeopardy activation) 3. Fill open shifts 4. Track duty hours 5. Address violations 6. Adjust for changing circumstances

  ---

  4. User Workflows

  4.1 Program Coordinator Workflows

  Creating Annual Rotation Schedule: 1. Configure blocks for new academic year 2. Set up resident roster (new interns, graduating seniors) 3. Define rotation requirements 4. Build schedule (drag-drop or auto-generate) 5. Review for conflicts and completeness 6. Get PD approval 7. Publish to residents

  Creating Monthly Call Schedule: 1. Select block/month and service 2. Review eligible residents (from rotation schedule) 3. Import approved time-off requests 4. Set daily staffing requirements 5. Generate schedule or build manually 6. Run compliance check 7. Review tally distribution 8. Adjust and finalize 9. Publish

  Handling Day-to-Day Changes: 1. Receive swap request or sick call 2. Find coverage (check jeopardy, post open shift) 3. Validate change doesn’t create violations 4. Update schedule 5. Notify affected parties

  4.2 Chief Resident Workflows

  Schedule Review: 1. Review draft schedule for fairness 2. Check that educational needs are met 3. Identify potential conflicts 4. Approve or suggest modifications

  Handling Swaps: 1. Receive swap request from residents 2. Verify both parties agree 3. Check ACGME compliance for both 4. Approve or deny 5. Update schedule

  Emergency Coverage: 1. Receive notification of sick resident 2. Check jeopardy resident availability 3. Activate jeopardy or find alternate coverage 4. Ensure compliant assignment 5. Update schedule and notify

  4.3 Resident Workflows

  Viewing Schedule: 1. Open schedule (web or mobile) 2. See personal assignments (today, this week, this month) 3. Sync to personal calendar 4. View who else is working (for coordination)

  Requesting Time Off: 1. Submit request with dates and reason 2. Track request status 3. Receive approval/denial notification 4. See updated schedule if approved

  Requesting Swap: 1. Find shift to trade 2. Identify willing trade partner 3. Submit swap request (both parties confirm) 4. Await approval 5. See updated schedule if approved

  Claiming Open Shift: 1. View available open shifts 2. Check personal schedule for conflicts 3. Claim shift 4. Receive confirmation 5. See updated schedule

  Logging Duty Hours (if system includes this): 1. Review pre-populated hours from schedule 2. Adjust for actual times (stayed late, left early) 3. Add at-home call time when doing patient care 4. Add moonlighting hours 5. Submit/confirm weekly hours

  ---

  5. Glossary Quick Reference

  Term	Definition
  ACGME	Accreditation Council for Graduate Medical Education
  Block	Fixed scheduling period (typically 2-4 weeks)
  Call	Extended duty period, often overnight
  Continuity Clinic	Recurring outpatient clinic assignment
  Cross-cover	Covering another team’s patients
  Duty Hours	Total work hours subject to ACGME limits
  Fellow	Post-residency subspecialty trainee
  GME	Graduate Medical Education
  Home Call	On-call from home (not in hospital)
  In-House Call	On-call while physically in hospital
  Intern	PGY-1 resident (first year)
  Jeopardy	Backup coverage system
  Moonlighting	Paid work outside residency duties
  Night Float	Rotation dedicated to night shifts
  PGY	Post-Graduate Year (training level)
  Q3, Q4, etc.	Call frequency (every 3rd night, 4th night, etc.)
  Rotation	Clinical assignment for a block period
  Service	Clinical team requiring coverage
  Shift	Discrete work period with set times
  Swap	Exchange of assignments between residents
  Tally	Running count for fairness tracking
  Violation	Exceeding ACGME duty hour limits

  ---

  6. Common Edge Cases

  6.1 Scheduling Edge Cases

  Resident transitions mid-block - Senior graduates or new resident starts mid-year - Resident switches programs - Handle partial block assignments

  Overlapping assignments - Resident on rotation A but taking call for rotation B - Clinic sessions during ward rotations - Research time during clinical rotations

  Variable shift lengths - Same shift type with different durations - Extended shifts for specific circumstances - Partial shifts

  6.2 Compliance Edge Cases

  Vacation during 4-week window - Vacation days excluded from day-off count - Hours calculations must exclude vacation periods

  Rotation shorter than 4 weeks - Use rotation length as averaging period - Don’t extrapolate to 4 weeks

  Moonlighting during light rotation - Still counts toward 80-hour limit - May push otherwise compliant schedule into violation

  Called in from home call - Only hospital time counts toward hours - Commute time does not count - Does not restart rest clock

  Working past scheduled time - Actual hours may exceed scheduled hours - System should track both scheduled and actual - Compliance based on actual hours worked

  6.3 Request Edge Cases

  Overlapping requests - Two residents request same day off - Swap request conflicts with existing time-off request

  Cascade effects - Approved request creates need for coverage - Coverage assignment causes violation for covering resident

  Last-minute changes - Sick call with no jeopardy available - All eligible residents already at hour limits

• Jeopardy Systems - Guava Docs

  Jeopardy Systems

  Jeopardy is the essential backup coverage mechanism that ensures continuous patient care when residents face unexpected absences. Programs without robust jeopardy systems face constant scrambles when residents call in sick, while well-designed systems improve both coverage reliability and resident wellness. This guide covers how jeopardy works in practice—activation workflows, common models, eligibility rules, and the challenges programs face.

  Defining jeopardy and its core purpose

  Jeopardy is a backup coverage system where designated residents remain on standby to provide coverage when another resident cannot work due to illness, family emergencies, bereavement, or other unforeseen circumstances. The term derives from the “jeopardy” of losing coverage—patient care is at risk until backup is activated.

  Critical distinction from “float” coverage: Jeopardy is exclusively for unexpected absences. Float residents handle workload distribution and planned coverage gaps. As University of Wisconsin explicitly states: “The Jeopardy resident is NOT available as a ‘float’ to cover individuals who wish to leave their assigned shifts early for personal or social reasons.” Anticipated absences (conferences, weddings, interviews) should be covered through pre-arranged schedule swaps, not jeopardy activation.

  Jeopardy serves three interrelated purposes. First, it ensures continuous patient care on services that depend heavily on resident staffing—primarily inpatient wards and ICUs. Second, it supports resident wellness by enabling time off without guilt or fear of negative consequences, which ACGME now explicitly requires. Third, it reduces administrative burden on chief residents who would otherwise scramble to fill gaps ad-hoc.

  How jeopardy activation works in practice

  The activation workflow follows a standard pattern across programs, with the chief resident serving as coordinator rather than allowing direct contact between the sick resident and their backup.

  Standard activation sequence: The absent resident contacts the chief resident on call (not the jeopardy resident directly). The chief evaluates whether jeopardy coverage is actually necessary—sometimes the service can absorb the absence. If coverage is needed, the chief activates the appropriate jeopardy tier (J1 first, J2 if J1 is unavailable). The jeopardy resident receives notification via page, text, or app push notification and must respond within 15-20 minutes and arrive at the hospital within 45-60 minutes for active jeopardy. The jeopardy resident notifies their current rotation attending and receives a basic clinical handoff.

  Typical triggers for activation include personal illness (most common), family emergencies, bereavement, medical appointments that cannot be rescheduled, and brief medical disability. Some programs also allow activation for capped teams when census exceeds safe limits, though this is controversial and risks overutilization.

  What should NOT trigger jeopardy: Car problems, routine doctor appointments, moonlighting conflicts, events known more than 24-72 hours in advance, or requests to leave shifts early. These should be handled through scheduled swaps or PTO.

  Common models for structuring jeopardy

  Programs have developed several distinct models, each with different tradeoffs for coverage reliability, resident experience, and administrative complexity.

  Tiered jeopardy systems

  The most common approach assigns multiple backup tiers with different response requirements. University of Colorado’s model illustrates this well:

  Tier	Response time	Restrictions
  Active Jeopardy (J1)	45-60 minutes	Must stay local, no mountain trips, no flights
  Backup Jeopardy (J2)	24 hours advance notice	No flights, must be able to return within 24 hours
  Tertiary (J3)	As needed	Contacted only if J1 and J2 exhausted

  J1 is activated first; J2 converts to active status only if J1 is unavailable or if multiple absences occur simultaneously. This layered approach provides flexibility—backup jeopardy residents can take day trips while still being available if needed.

  Dedicated jeopardy-elective rotations

  UCLA Pathology developed an innovative model where jeopardy becomes a formal rotation. Each resident is assigned 4 “Jeopardy-Elective” (JE) rotations over their training, combining standby coverage duty with elective time. When not covering absences, JE residents work on electives of their choice.

  Results from this model were positive: residents covered an average of 8.5 days out of 20 workdays per JE rotation, satisfaction with taking sick days improved significantly (p=0.03), and 82% of residents wanted to retain the system. The model also increased PTO usage from 16 to 20 days per resident annually—suggesting residents felt more comfortable taking time off.

  Pool-based daily assignments

  Larger programs (130+ residents) often assign two residents per day as “A” (first-call) and “B” (second-call) jeopardy, drawn from those on elective or outpatient rotations. This distributes the burden widely—typically 2 jeopardy days per month per eligible resident.

  Weekly assignment model

  Smaller programs may assign one resident per week as the designated jeopardy coverage. This creates longer on-call windows but simpler scheduling. The jeopardy resident treats it as a “work from home” week when not activated—available by pager but continuing their elective work remotely.

  Who is eligible for the jeopardy pool

  Eligibility rules determine which residents can be assigned to jeopardy, and these rules need to be built into any scheduling software.

  Eligible rotations: Residents on outpatient clinics, electives, research blocks, non-clinical rotations, or administrative time. The key criterion is whether the rotation can absorb the resident’s absence—clinics that operate without trainees are ideal jeopardy-eligible assignments.

  Ineligible rotations: Residents on vacation, inpatient services, ICU, night float, or high-acuity procedural services cannot be jeopardized. Their current assignment cannot absorb their absence.

  Training level matching: Coverage should be provided by residents at the same PGY level or higher. A PGY-2 cannot cover for a PGY-3 on a service requiring senior-level competency. For subspecialty services, the covering resident must have completed relevant rotations—cardiac anesthesia jeopardy requires prior cardiac rotation experience.

  First-year exclusions: Many programs exclude CA-1s and interns from jeopardy during their first month (or longer) until they have sufficient service experience to provide meaningful coverage.

  Moonlighting conflicts: Residents cannot moonlight while on jeopardy. If activated, their external commitment creates a conflict. Most programs explicitly prohibit scheduling moonlighting during jeopardy periods.

  ACGME duty hour constraints on jeopardy

  ACGME does not use the term “jeopardy” in its regulations, but jeopardy systems must operate within the duty hour framework. All time worked during jeopardy activation counts toward ACGME limits—there is no exemption for backup coverage.

  Core constraints affecting jeopardy

  80-hour weekly maximum: Clinical and educational work hours cannot exceed 80 hours per week, averaged over four weeks. When jeopardy is activated, those hours count fully. Programs scheduling residents near 80 hours should build in buffer—ACGME explicitly notes that programs “that regularly schedule residents to work 80 hours per week and permit trainee flexibility are likely to exceed 80 weekly hours.”

  Maximum shift length (24+4 hours): Continuous clinical work cannot exceed 24 hours, with up to 4 additional hours permitted only for transitions of care. If a jeopardy resident is already working and gets called in, total continuous work cannot breach this limit.

  Time off between shifts: Residents must have at least 14 hours free after 24 hours of in-house call. For shorter shifts, 8 hours off is recommended (but not required). Post-jeopardy, if the resident worked overnight, they cannot have clinical duties for at least 10-14 hours.

  One day off in seven: Residents must have one day in seven free of clinical work, averaged over four weeks (4 days off per 28-day block). Critically, jeopardy cannot be assigned on these required days off. If a resident is on jeopardy and gets called in on a scheduled day off, that day no longer counts as a day off for compliance purposes.

  Home call versus in-house jeopardy

  Home call jeopardy (most common): The resident stays home but must be reachable and able to arrive within 45-60 minutes. ACGME does not require a day off after home call, but if the resident comes in and works, those hours count toward the 80-hour limit.

  In-house jeopardy (less common): The resident stays overnight at the hospital. ACGME requires the following day off. This is typically reserved for high-acuity services requiring immediate availability.

  Compliance tracking requirements

  Programs must track jeopardy activations and log them appropriately. When jeopardy is activated, the shift must be recorded in duty hour tracking systems (MedHub, New Innovations). The key logging distinction: “At-Home Call—Not Called In” does not count toward 80 hours; “At-Home Call—Called In” must be counted.

  Best practices for jeopardy scheduling

  Research and program documentation reveal several practices that distinguish effective jeopardy systems.

  Centralized coordination through chiefs: The sick resident should never contact the jeopardy resident directly. Chiefs coordinate across multiple services and can determine if jeopardy is actually necessary—sometimes the service can absorb an absence.

  Transparent fairness tracking: Programs should track how many jeopardy shifts each resident covers and use this data to distribute future assignments equitably. However, programs should NOT track how many days each resident uses jeopardy—this discourages appropriate use and perpetuates the “culture of bravado when it came to toughing it out through illness.”

  Clear activation criteria: Document explicitly what does and does not warrant jeopardy activation. Ambiguity leads to overutilization (busy services calling jeopardy for high census rather than true absences) or underutilization (residents coming in sick because they’re unsure if their situation qualifies).

  Payback policies with caution: Some programs require payback when jeopardy is used. University of Colorado uses a 3:1 penalty ratio for missed jeopardy—miss your assignment, owe three shifts to the covering resident. This can promote accountability but risks creating punitive culture. Other programs use point-based systems where covering earns points and requesting deducts them, with points influencing future jeopardy priority.

  Response time enforcement: Active jeopardy residents should respond to pages within 15 minutes and arrive within 45-60 minutes. Some programs treat failure to respond as a professionalism issue.

  Challenges and pain points programs face

  Understanding the problems programs encounter helps inform software design decisions.

  Overutilization and definitional ambiguity: UCLA’s study found the primary modification request was “further clarifying instances where Jeopardy should be called and to prevent overutilization by busy services.” Without clear guidelines, jeopardy gets activated for inappropriate reasons—unexpectedly high case volume, fellow absences, inexperienced residents struggling.

  Unfair distribution: Before automated scheduling, variance in jeopardy assignments created resentment. Manual scheduling makes equitable distribution nearly impossible across an academic year. Yale’s AIMS automated scheduling tool explicitly measured and reduced this variance.

  Chief resident burden: Manual scheduling is described as “NP-complete”—exponentially more complex with more trainees and rotations. Chiefs spend weeks creating schedules and still produce errors. Automation reduced this task from weeks to days and made it “much more enjoyable.”

  Unpredictability stress: Residents on jeopardy cannot plan activities, take weekend trips, or schedule exams. They must keep pagers on and stay geographically constrained. This creates ongoing low-grade stress even when jeopardy is never activated.

  Cultural barriers to appropriate use: Many physicians work sick “because of obligations to colleagues and patient care.” The word “jeopardy” itself implies danger, potentially discouraging use. Some have suggested renaming it “Family Emergency/Illness Patient Care Backup.”

  Specialty-specific variations

  Different specialties have distinct jeopardy requirements reflecting their clinical patterns.

  Internal medicine uses tiered systems (J1/J2/J3) with separate intern and resident pools. Point-based tracking promotes fairness. Coverage includes wards, ICU, and admissions. Some programs trigger jeopardy for capped teams when census exceeds safe limits.

  Surgery often links jeopardy to moonlighting privileges—lab residents (research years) form the primary pool. Coverage requires procedural competency, so subspecialty matching is critical. UCSF caps jeopardy at 3 consecutive days or 24 consecutive hours and pays standard moonlighting rates for activated shifts.

  Anesthesiology requires strict class-level matching (CA-1s cover CA-1 cases only) and subspecialty-specific coverage. The ASA recommends 2:1 repayment for missed coverage and excluding CA-1s during their first month.

  Emergency medicine operates on shift-based models rather than traditional call, making jeopardy conceptually different—more like “backup shifts” scheduled 24 hours in advance. Night float systems are more common than traditional jeopardy. ShiftAdmin is the dominant platform (53% market share).

  Pathology has implemented the Jeopardy-Elective rotation model most successfully, leveraging the specialty’s less time-critical nature. First-year residents are excluded due to insufficient service experience.

  Program size matters significantly: Small programs (≤30 residents) have limited jeopardy pool depth and may rely on attending coverage when the pool is exhausted. Jeopardy activations are rare—sometimes once or twice per year. Large programs (130+ residents) need deep pools, sophisticated tiered systems, and robust tracking. Academic medical centers face additional complexity from multiple training sites, fellow involvement, and research rotations expanding the eligibility pool.

  Key takeaways

  Effective jeopardy systems balance three competing demands: reliable coverage, resident wellness, and administrative simplicity.

  The most successful programs treat jeopardy as infrastructure for wellness rather than punishment for sick residents. Key elements include: - Tiered activation that provides flexibility while ensuring coverage - Clear eligibility rules based on rotation type, PGY level, and subspecialty experience - Fairness tracking for shifts covered (but not for days used—that discourages appropriate use) - Centralized coordination through chief residents rather than direct contact

  The UCLA Jeopardy-Elective model offers a compelling example: formal jeopardy rotations that provide both reliable coverage and protected elective time, with documented improvements in resident satisfaction and PTO utilization.

• Domain Reference - Guava Docs

  Domain Reference

  Reference documentation for the medical residency program administration domain. These documents capture domain knowledge essential for product development, serving as shared context for both humans and LLMs when writing specs, designing features, and making implementation decisions.

  Contents

  Document	Description
  call-scheduling-reference.md	Comprehensive guide to call scheduling - terminology, ACGME duty hour rules, scheduling concepts, user workflows, and common edge cases
  jeopardy-systems.md	Deep dive into jeopardy (backup coverage) systems - activation workflows, common models, eligibility rules, ACGME constraints, best practices, and specialty variations

  Purpose

  These references help answer domain questions like: - What roles exist in a residency program? - What does “Q3 call” mean? - What are the ACGME duty hour limits? - How does jeopardy activation work in practice? - What workflows do coordinators and chief residents follow?

  Contributing

  Update these documents as we learn new domain knowledge from: - User research and interviews - Competitive analysis - Industry documentation - Implementation discoveries

  Keep documents factual and descriptive rather than prescriptive about our product. These describe the domain, not our solution.

• Scheduling Principles - Guava Docs

  Scheduling Principles

  This document defines the guiding principles for building call and rotation scheduling in Guava. These principles establish a conceptual framework that all scheduling features should follow.

  Core Architecture: Separation of Concerns

  Scheduling is organized around three distinct systems that interact but don’t conflate:

  1. The Plan — What the solver produces (proposals, scenarios)
  2. The Record — What actually happened (operational truth)
  3. The Rules — Constraints that guide the solver and flag violations

  ---

  The Plan

  Principle: The solver is a tool, not an authority.

  The solver produces proposals, not mandates. Humans evaluate and adopt them.

  Implications

  • Solve at any time — Run the solver whenever needed: fresh, incremental, what-if scenarios. The system never says “you already solved this.”

  • Solve with constraints — Lock specific assignments, date ranges, or residents. Example: “Keep everything before March 15, re-solve the rest.”

  • Multiple proposals can coexist — Run different scenarios (with/without a resident, different constraint weights) and compare before committing.

  • Proposals don’t automatically become reality — An admin explicitly promotes a proposal to the operational schedule.

  ---

  The Record

  Principle: The operational schedule reflects reality, not intentions.

  The Record is the source of truth for what actually happened (or will happen). It answers “what actually happened?” not “what should have happened?”

  Implications

  • The Record is editable — When reality changes (swap, dropout, sick call), the Record updates to match. No fighting the system to record truth.

  • The Record is distinct from proposals — A proposal gets promoted to the Record, but after that, the Record lives independently. Re-running the solver doesn’t automatically change the Record.

  • The Record can contain rule violations — If a resident worked a shift that violated a constraint, the Record captures that it happened. Reality trumps rules.

  • Every mutation is attributed (including creation):

    • Source: What caused the change (solver promotion, manual creation, swap request)
    • Actor: Who took the action
    • Timestamp: When it happened
    • Context: Why, if provided (reason for swap, override justification)

  • Full history is preserved — Any assignment can be traced back to its origin and every modification since. No assignment appears in The Record without knowing who put it there and why.

  ---

  The Rules

  Principle: Rules are hard or soft, never mushy.

  Rules guide the solver and validate the schedule. But rules serve the program, not the other way around.

  Hard vs Soft Constraints

  • Hard constraints — Solver will not violate these. To allow a violation, you must explicitly override that specific instance.

  • Soft constraints — Solver optimizes toward these but can trade them off against each other. Violations aren’t errors; they’re optimization outcomes with costs.

  There is no “warn but allow” middle ground that erodes rule integrity over time.

  Constraint Override Hierarchy

  Hard constraints are configurable at granular levels through a cascading override system. More specific scopes override broader ones:

  Global default (constraint definition) └── Program-level override └── Schedule-level override └── Time-range override (e.g., "July 2025") └── Resident-level override └── Specific instance override (resident + time)

  Example: “Max night calls per month” defaults to 4. Dr. Smith has an override for July 2025 allowing 6 (covering for resident on leave). The base rule stays clean; the override documents the exception.

  Benefits of Override Hierarchy

  • Base rules stay clean and auditable
  • Overrides are explicit and scoped
  • Easy to answer “why was this allowed?” — look at the override chain
  • Overrides can expire (time-scoped) without cleanup

  Implications

  • Explicit overrides — When a rule must be violated, an admin explicitly acknowledges it. This creates a record: “Night call limit exceeded for Dr. Smith on 3/15 — approved by Jane (emergency coverage).”

  • Overrides attach to specific violations — You’re not disabling a rule globally; you’re approving a specific exception.

  • Post-hoc overrides are valid — If something already happened that violated a rule, you can record it with an override explanation.

  • Rules don’t block recording reality — The Record always accepts what happened. Rules flag violations for visibility.

  ---

  Cross-Cutting Principles

  These principles govern how The Plan, The Record, and The Rules interact:

  Solving is always available

  • Run the solver at any time: fresh start, incremental, what-if
  • Lock any subset: date ranges, specific assignments, residents
  • Compare multiple proposals before committing
  • A resident leaving mid-schedule? Lock the past, re-solve the future

  Promotion is explicit

  • Proposals don’t become operational automatically
  • An admin explicitly promotes a proposal (or parts of it) to The Record
  • Promotion is a deliberate act, not a side effect of solving

  The Record is sovereign

  • Once promoted, The Record lives independently from proposals
  • Re-solving doesn’t change The Record — it produces new proposals
  • The Record can be edited directly (swaps, corrections, additions)
  • Edits are tracked for accountability, not gated by rules

  Rules inform, violations are visible

  • Hard constraints block the solver unless exempted via override hierarchy
  • Soft constraints guide optimization with trade-offs
  • The Record flags violations but accepts reality
  • Exemptions and overrides are documented, not hidden

  ---

  Summary

  System	Purpose	Key Property
  The Plan	Solver proposals	Advisory, explorable, comparable
  The Record	Operational truth	Sovereign, auditable, reality-accepting
  The Rules	Constraints	Hard or soft, overridable at granular levels

  These principles ensure that scheduling remains a tool that serves the program’s needs while maintaining clear accountability and the flexibility to handle real-world complexity.

General

• Frontend Development Guide - Guava Docs

  Frontend Development Guide

  This guide covers frontend development patterns and conventions for the Guava frontend.

  Structure

  frontend/ ├── app/ │ ├── routes/ # Route components (file-based routing) │ │ ├── home.tsx # / (index route) │ │ ├── auth.login.tsx # /auth/login │ │ ├── p.$token.tsx # /p/:token (public preference entry) │ │ ├── rotation-schedules.new.tsx # /rotation-schedules/new │ │ └── rotation-schedules.$id.setup.tsx # /rotation-schedules/:id/setup │ ├── routes.ts # Route configuration (CRITICAL!) │ ├── gen/ # Generated protobuf types (from backend) │ ├── components/ # UI components │ │ └── ui/ # shadcn/ui components (owned by you) │ ├── lib/ # Shared utilities │ │ ├── connect-client.ts # Connect RPC client setup │ │ ├── auth-context.tsx # Auth state management │ │ ├── query-provider.tsx # React Query setup │ │ └── utils.ts # Utility functions (cn helper) │ ├── root.tsx # Root layout component │ └── app.css # Global styles (Tailwind + shadcn theme)

  React Router v7 Configuration

  CRITICAL: React Router v7 uses explicit route configuration in frontend/app/routes.ts. File names like auth.login.tsx do NOT automatically create routes. You MUST manually register all routes.

  When adding a new route: 1. Create the route file in frontend/app/routes/ (e.g., auth.login.tsx) 2. IMMEDIATELY add it to frontend/app/routes.ts: typescript export default [ index("routes/home.tsx"), // / (root) route("auth/login", "routes/auth.login.tsx"), // /auth/login // ... other routes ] satisfies RouteConfig; 3. The dev server will hot-reload with the new route

  Common mistake: Creating a route file but forgetting to register it in routes.ts results in 404 errors.

  Development Commands

  cd frontend pnpm install # Install dependencies pnpm run dev # Start dev server (usually on :5173 or :5174) pnpm run build # Build for production pnpm run typecheck # Run TypeScript type checking pnpm run lint # Run Biome linting pnpm run lint:fix # Auto-fix linting issues pnpm run format # Format code with Biome pnpm run format:check # Check code formatting

  UI Components (shadcn/ui)

  The frontend uses shadcn/ui - a collection of reusable components built on Radix UI.

  Adding New Components:

  cd frontend pnpm dlx shadcn@latest add [component-name] # e.g., button, input, dialog, tabs

  Key Features: - Components live in app/components/ui/, you own the code - Built on Radix UI with accessibility support - Tailwind CSS for styling - Documentation: https://ui.shadcn.com/docs

  Code Quality & Type Safety

  Biome handles linting and formatting (replaces ESLint + Prettier).

  Code Style: - Double quotes, semicolons required - 2-space indentation, 100 char line width

  Type Safety Requirements: - NO type casting/assertions - Type assertions (as Type) are prohibited except: - as const for literal type narrowing - Context default values in React (e.g., {} as ContextType) - Use type guards and validation - Validate data at runtime instead of asserting - Form data extraction - Use getRequiredFormField() or getOptionalFormField() from ~/lib/form-utils - Strict TypeScript - noUncheckedIndexedAccess and all strict flags enabled - No explicit any - Biome enforces noExplicitAny: "error" - No non-null assertions - Biome enforces noNonNullAssertion: "error"

  Type Guard Pattern:

  // Single source of truth - array defines the type const VALID_THEMES = ["dark", "light", "system"] as const; type Theme = (typeof VALID_THEMES)[number];  function isValidTheme(value: string): value is Theme {  return VALID_THEMES.some((t) => t === value); }  function toTheme(value: string, fallback: Theme = "system"): Theme {  return VALID_THEMES.find((t) => t === value) ?? fallback; }

  Authentication

  The frontend uses HTTP-only cookie authentication:

  1. User logs in via /auth/login → backend sets session_token HTTP-only cookie
  2. Frontend automatically includes cookies via credentials: "include"
  3. Backend validates session from cookie on each request

  Key Files: - frontend/app/lib/auth-context.tsx - Manages auth state via getCurrentUser() RPC - frontend/app/lib/connect-client.ts - Provides transport with automatic cookie handling - frontend/app/lib/protected-route.tsx - Wrapper component to protect routes

  Making Authenticated API Calls:

  import { createClient } from "@connectrpc/connect"; import { UserService } from "~/gen/user/v1/user_pb"; import { transport } from "~/lib/connect-client";  function MyComponent() {  const client = createClient(UserService, transport);  // Cookies automatically included }

  Protecting Routes:

  import { ProtectedRoute } from "~/lib/protected-route";  export default function MyPage() {  return (  <ProtectedRoute>  <MyPageContent />  </ProtectedRoute>  ); }

  Data Loading Pattern

  Use direct useQuery with a null guard. No loaders, no loading spinners.

  Standard Pattern

  import { useQuery } from "@connectrpc/connect-query"; import { listSites } from "~/gen/site/v1/site-SiteService_connectquery";  function SitesContent() {  const { data } = useQuery(listSites);   if (!data) return null;   // data is guaranteed to exist after this point  const sites = data.sites;  return <SitesList sites={sites} />; }

  Multiple Queries

  function ScheduleContent({ id }: { id: string }) {  const { data: scheduleData } = useQuery(getSchedule, { id });  const { data: blocksData } = useQuery(listBlocks, { scheduleId: id });   if (!scheduleData || !blocksData) return null;   // Both guaranteed to exist }

  Rules

  1. No clientLoader exports - Loaders add complexity without benefit
  2. No isPending / isLoading checks - Backend is fast, spinners feel slower
  3. Guard with if (!data) return null - Shows nothing until data arrives
  4. After the guard, data is guaranteed - No optional chaining needed

  What Happens at Runtime

  • AppLayout (sidebar, header) renders immediately
  • Content area is empty for 100-200ms while data fetches
  • Data arrives, content appears
  • On revisit: cached data shows instantly (stale-while-revalidate)

  Program-Scoped Queries

  Many endpoints require a programId parameter. To prevent requests from firing with empty programId before the context is initialized, use the program-scoped query hooks from ~/lib/program-queries.ts.

  Available hooks: - useProgramResidents() - Fetches residents in the current program - useProgramRotationSchedules() - Fetches rotation schedules in the current program - useProgramAcademicYears() - Fetches academic years in the current program - useProgramCallSchedules() - Fetches call schedules in the current program

  How they work: 1. Each hook checks both !isLoading and !!currentProgramId before enabling the query 2. Queries NEVER fire with an empty programId 3. Components render immediately (no blocking spinner) while queries wait for programId

  Usage:

  import { useProgramResidents } from "~/lib/program-queries";  function ResidentsContent() {  const { data } = useProgramResidents();   if (!data) return null;   return <ResidentsList residents={data.residents} />; }

  CRITICAL: Do NOT call program-scoped endpoints directly:

  // DON'T DO THIS - risks empty programId const { data } = useQuery(listResidents, { programId: someProgramId ?? "" });  // DO THIS - uses the safe wrapper hook const { data } = useProgramResidents();

  For other program-scoped endpoints, follow the pattern in program-queries.ts:

  export function useProgramNewFeature() {  const { currentProgramId, isLoading } = useProgram();  const enabled = !isLoading && !!currentProgramId;  return useConnectQuery(listNewFeature, { programId: currentProgramId ?? "" }, { enabled }); }

  Data Fetching in Dialogs

  Convention: Dialogs receive reference data as props from their parent. They do not fetch it themselves.

  Dialog components (modals, drawers, etc.) should not call useQuery or useProgramX() hooks to fetch reference data like rotations, sites, tags, or residents. Instead, the parent component that renders the dialog should fetch shared data and pass it down as props.

  Why: - Makes data dependencies explicit — you can see from the outside what a dialog needs - Eliminates duplicate fetching logic when sibling dialogs share the same data - Makes components easier to test in isolation - TanStack Query deduplicates at the network level, but the code-level duplication still obscures intent

  Correct:

  // Parent fetches and passes data function SchedulePage() {  const { data: sitesData } = useProgramSites();  const sites = sitesData?.sites ?? [];   return (  <CreateShiftDialog sites={sites} callScheduleId={id} />  ); }  // Dialog receives data as props interface CreateShiftDialogProps {  sites: Site[];  callScheduleId: string; }  function CreateShiftDialog({ sites, callScheduleId }: CreateShiftDialogProps) {  // Use sites directly — no fetching here }

  Incorrect:

  // Dialog fetches its own reference data function CreateShiftDialog({ callScheduleId }: { callScheduleId: string }) {  const { data: sitesData } = useProgramSites(); // DON'T — hoist to parent  const sites = sitesData?.sites ?? []; }

  Exceptions — dialogs may fetch data internally when: - The query is specific to that dialog and no sibling shares it (e.g., listResidentTagCombinations in a single dialog) - The query depends on dialog-internal state (e.g., a search query typed by the user) - Mutations — dialogs always own their own useConnectMutation calls

  Mutation Patterns & Cache Invalidation

  All mutation → query invalidation relationships are defined in frontend/app/lib/query-relationships.ts: - Single source of truth for which queries need invalidation after each mutation - Automatic invalidation via MutationCache.onSuccess in query-provider.tsx

  Adding a new mutation: 1. Import the mutation from the connect-query generated file 2. Import any query schemas it affects 3. Add an entry to mutationEffects:

  [createFoo.name]: [listFoos, getFoo],

  Component mutations:

  // DO THIS: Simple useMutation with no onSuccess invalidation const createMutation = useMutation(createFoo);  // onSuccess is only for UI state changes const createMutation = useMutation(createFoo, {  onSuccess: () => {  setIsDialogOpen(false);  form.reset();  }, });

  NEVER manually invalidate in components - the central schema handles it.

  Important Files

  • frontend/app/routes.ts - Route configuration (MUST be updated when adding routes)
  • frontend/app/root.tsx - Root layout with providers
  • frontend/app/lib/connect-client.ts - RPC client configuration
  • frontend/app/lib/auth-context.tsx - Authentication state management
  • frontend/app/lib/query-provider.tsx - TanStack Query with MutationCache auto-invalidation
  • frontend/app/lib/query-relationships.ts - Central mutation → query schema
  • frontend/app/lib/form-utils.ts - Type-safe form data extraction
  • frontend/app/components/ui/ - shadcn/ui components
  • frontend/biome.json - Biome linter and formatter configuration
  • frontend/tsconfig.json - TypeScript configuration
  • frontend/app/gen/ - Generated TypeScript types from protobuf
• Local SSO Testing with Keycloak - Guava Docs

  Local SSO Testing with Keycloak

  This guide explains how to test OIDC and SAML authentication locally using Keycloak.

  Prerequisites

  • Docker installed and running
  • Local PostgreSQL database (make db)
  • Backend running with SSO environment variables

  Quick Start

  # 1. Start PostgreSQL (if not already running) make db  # 2. Start Keycloak make keycloak  # 3. Set up SSO environment variables cp .envrc.example .envrc source .envrc  # 4. Seed SSO test data make seed-sso  # 5. Start dev environment make dev-sso # Starts backend with SSO enabled

  Test Credentials

  Email	Password	Auth Method
  alice@oidc-test.local	password123	OIDC
  bob@saml-test.local	password123	SAML

  Testing OIDC Flow

  1. Go to http://localhost:5173/auth/login
  2. Enter alice@oidc-test.local
  3. Click “Continue”
  4. You’ll be redirected to Keycloak
  5. Log in with password123
  6. You’ll be redirected back to the app, logged in

  Testing SAML Flow

  1. Go to http://localhost:5173/auth/login
  2. Enter bob@saml-test.local
  3. Click “Continue”
  4. You’ll be redirected to Keycloak
  5. Log in with password123
  6. You’ll be redirected back to the app, logged in

  Keycloak Admin Console

  • URL: http://localhost:8180
  • Username: admin
  • Password: admin

  Use this to: - View/edit test users - Check client configurations - Debug SSO issues

  Troubleshooting

  “OIDC SSO handler registered” not in logs

  Ensure environment variables are set:

  source .envrc make dev-sso

  “SAML SSO handler registered” not in logs

  Ensure SP_CERT and SP_KEY are set and the cert files exist:

  ls docker/keycloak/sp-*.pem cat docker/keycloak/sp-cert.pem | head -1 # Should show BEGIN CERTIFICATE

  Keycloak not starting

  Check Docker logs:

  make keycloak-logs

  “institution not found” error

  Ensure SSO data is seeded:

  make seed-sso

  Redirect loop or callback errors

  1. Check Keycloak is running: curl http://localhost:8180/health/ready
  2. Check redirect URIs match in Keycloak admin console
  3. Check SSO_ROOT_URL is http://localhost:8080

  Makefile Commands

  Command	Description
  make keycloak	Start Keycloak container
  make keycloak-stop	Stop and remove Keycloak
  make keycloak-logs	Tail Keycloak logs
  make seed-sso	Seed SSO test data

plans

• Call Schedule Constraints — Design - Guava Docs

  Call Schedule Constraints — Design

  Motivation

  Establish DDD/hexagonal architecture as the standard pattern for the codebase, using call schedule constraints as the reference implementation. Constraints are configuration that the solver will eventually consume, but solver integration is out of scope here.

  Constraint Types

  Two buckets of constraints, all program-scoped and associated with schedules via per-type join tables.

  Bucket A: Rest Constraints

  Rules about the gap between two shifts for a resident.

  MinRestConstraint — covers three ACGME rules in one model:

  ACGME Rule	Configuration
  8h rest between clinical work (6.21)	restMode=FIXED, fixedHours=8, shiftFilter=ALL
  14h rest after 24h in-house call (6.21)	restMode=FIXED, fixedHours=14, afterMinDurationHours=24, shiftFilter=ALL
  EM: rest >= shift length between ED shifts	restMode=PROPORTIONAL, multiplier=1.0, shiftFilter=BY_CALL_TYPES([ED])

  Fields: - id, program_id, name - rest_mode — FIXED_HOURS or PROPORTIONAL - fixed_hours — set when FIXED_HOURS (e.g., 8, 14) - multiplier — set when PROPORTIONAL (e.g., 1.0 = shift length) - after_min_duration_hours — optional trigger: only applies after shifts >= N hours (nil = always) - shift_filter — which shifts this applies between (ALL, BY_CALL_TYPES, BY_TEMPLATES) - resident_filter — which residents (PGY range + tags)

  Bucket B: Limit Constraints

  Rules about measuring aggregate shift activity for a resident.

  MaxShiftFrequency — Q3 rule (ACGME 6.27):

  ACGME Rule	Configuration
  No more than every 3rd night, averaged over 4 weeks	maxEveryNNights=3, averagingWeeks=4
  IM: strict every-third-night (no averaging)	maxEveryNNights=3, averagingWeeks=0

  Fields: - id, program_id, name - max_every_n_nights — e.g., 3 for Q3 - averaging_weeks — e.g., 4; 0 = strict (no averaging) - shift_filter, resident_filter

  RequiredDayOff — 1 day in 7 rule (ACGME 6.21.b):

  ACGME Rule	Configuration
  1 day in 7, averaged over 4 weeks	daysPerWeek=1, averagingWeeks=4
  EM: 1 day in 7, strict per week	daysPerWeek=1, averagingWeeks=0

  Fields: - id, program_id, name - days_per_week — e.g., 1 - averaging_weeks — e.g., 4; 0 = strict per week - shift_filter, resident_filter

  MaxWeeklyHours — 80h rule (ACGME 6.20):

  ACGME Rule	Configuration
  80h/week averaged over 4 weeks	maxHours=80, averagingWeeks=4
  EM: 60h/week in ED	maxHours=60, averagingWeeks=4, shiftFilter=BY_CALL_TYPES([ED])

  Fields: - id, program_id, name - max_hours — e.g., 80, 60 - averaging_weeks — e.g., 4 - shift_filter, resident_filter

  Shared Value Objects

  ShiftFilter — which shifts a constraint applies to: - filter_type — ALL, BY_CALL_TYPES, BY_TEMPLATES - ids — list of call_type_id or template_id (empty when ALL)

  Include-only semantics. No exclude mode.

  ResidentFilter — which residents a constraint applies to: - pgy_min, pgy_max — optional PGY range - resident_tag_ids — optional list with AND logic (must have ALL tags)

  Nil/empty means “applies to all residents.”

  Schedule Association

  Constraints are program-level entities associated with schedules via per-type join tables (like the existing call_schedule_templates pattern):

  • call_schedule_min_rest_constraints (call_schedule_id FK, constraint_id FK)
  • call_schedule_max_shift_frequency_constraints (call_schedule_id FK, constraint_id FK)
  • call_schedule_required_day_off_constraints (call_schedule_id FK, constraint_id FK)
  • call_schedule_max_weekly_hours_constraints (call_schedule_id FK, constraint_id FK)

  Per-type join tables give proper FK integrity to each constraint’s detail table.

  Double duty: The association serves two purposes: 1. “Apply this constraint when solving this schedule” 2. “When checking this constraint, also consider shifts from the other schedules it’s associated with”

  Associating a constraint with a new schedule automatically widens the cross-schedule scope for all other schedules sharing that constraint.

  Domain Layer

  All types live within the existing call domain: internal/features/call/domain/.

  domain/ constraint_min_rest.go # MinRestConstraint constraint_max_shift_frequency.go # MaxShiftFrequency constraint_required_day_off.go # RequiredDayOff constraint_max_weekly_hours.go # MaxWeeklyHours constraint_shared.go # ShiftFilter, ResidentFilter, enums

  Each file contains: - Domain struct with unexported fields - Constructor with validation (NewMinRestConstraint(...)) - Reconstitute function for loading from persistence - Getters

  No behavior beyond construction validation — these are configuration entities, not aggregates with state transitions.

  Repository Interfaces

  One repository per constraint type, defined in domain/:

  type MinRestConstraintRepository interface {  Get(ctx context.Context, id uuid.UUID) (*MinRestConstraint, error)  Save(ctx context.Context, constraint *MinRestConstraint) error  Delete(ctx context.Context, id uuid.UUID) error  ListByProgram(ctx context.Context, programID uuid.UUID) ([]*MinRestConstraint, error)  ListBySchedule(ctx context.Context, scheduleID uuid.UUID) ([]*MinRestConstraint, error)  AssociateWithSchedule(ctx context.Context, constraintID, scheduleID uuid.UUID) error  DissociateFromSchedule(ctx context.Context, constraintID, scheduleID uuid.UUID) error }

  Same pattern for the other three types.

  Persistence

  Constraint Tables

  CREATE TABLE call_min_rest_constraints (  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),  program_id UUID NOT NULL REFERENCES programs(id) ON DELETE CASCADE,  name TEXT NOT NULL,  rest_mode TEXT NOT NULL CHECK (rest_mode IN ('fixed_hours', 'proportional')),  fixed_hours INT,  multiplier DOUBLE PRECISION,  after_min_duration_hours INT,  shift_filter_type TEXT NOT NULL CHECK (shift_filter_type IN ('all', 'by_call_types', 'by_templates')),  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),  CONSTRAINT valid_rest_config CHECK (  (rest_mode = 'fixed_hours' AND fixed_hours IS NOT NULL AND multiplier IS NULL) OR  (rest_mode = 'proportional' AND multiplier IS NOT NULL AND fixed_hours IS NULL)  ),  UNIQUE(program_id, LOWER(name)) );  -- Shift filter detail: which call types or templates CREATE TABLE call_min_rest_constraint_shift_filters (  constraint_id UUID NOT NULL REFERENCES call_min_rest_constraints(id) ON DELETE CASCADE,  ref_id UUID NOT NULL, -- call_type_id or template_id depending on parent's filter_type  PRIMARY KEY (constraint_id, ref_id) );  -- Resident filter detail: which tags CREATE TABLE call_min_rest_constraint_resident_tags (  constraint_id UUID NOT NULL REFERENCES call_min_rest_constraints(id) ON DELETE CASCADE,  resident_tag_id UUID NOT NULL REFERENCES resident_tags(id) ON DELETE CASCADE,  PRIMARY KEY (constraint_id, resident_tag_id) );  -- PGY range lives on the main table as pgy_min/pgy_max columns

  Same pattern for the other three constraint types. Each gets: - Main constraint table - Shift filter detail table - Resident tag filter table - Schedule association join table

  Schedule Association Tables

  CREATE TABLE call_schedule_min_rest_constraints (  call_schedule_id UUID NOT NULL REFERENCES call_schedules(id) ON DELETE CASCADE,  constraint_id UUID NOT NULL REFERENCES call_min_rest_constraints(id) ON DELETE CASCADE,  PRIMARY KEY (call_schedule_id, constraint_id) );

  Out of Scope

  • Solver integration — constraints are config only; translating to OR-Tools comes later
  • Soft targets — shift count targets and fairness/balance requirements deferred (see 2026-02-28-soft-targets-future.md)
  • Max continuous duty — redundant with rest constraints when min rest is enforced
  • Frontend UI — proto definitions and RPC service needed but implementation details deferred to planning phase
  • Constraint validation against each other — e.g., detecting contradictory constraints
• Required Institutions on Programs, Remove from Users
• Required Institutions Implementation Plan - Guava Docs

  Required Institutions Implementation Plan

  For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

  Goal: Make institution_id NOT NULL on programs (with CASCADE delete) and remove institution_id from users entirely.

  Architecture: Two schema changes propagate through generated code, services, tests, and seed data. The SSO institution-mismatch check switches from reading user.institution_id to verifying the user’s email domain against institution_domains.

  Tech Stack: Go, sqlc, PostgreSQL, Connect RPC, Protocol Buffers

  ---

  Task 1: Update migration — programs.institution_id NOT NULL, drop from users

  Files: - Modify: internal/db/migrations/001_initial_schema.sql

  Step 1: Edit the programs table

  Change line 58 from:

  institution_id UUID REFERENCES institutions(id) ON DELETE SET NULL,

  to:

  institution_id UUID NOT NULL REFERENCES institutions(id) ON DELETE CASCADE,

  Step 2: Edit the users table

  Remove line 89:

  institution_id UUID REFERENCES institutions(id) ON DELETE SET NULL,

  Remove line 96:

  CREATE INDEX idx_users_institution_id ON users(institution_id);

  Step 3: Commit

  git add internal/db/migrations/001_initial_schema.sql git commit -m "schema: make institution_id NOT NULL on programs, drop from users"

  ---

  Task 2: Update SQL queries

  Files: - Modify: internal/features/program/queries.sql - Modify: internal/features/user/queries.sql - Modify: internal/features/institution/queries.sql

  Step 1: Program queries — no changes needed

  CreateProgram already accepts institution_id as $3. UpdateProgramInstitution still makes sense. No changes to internal/features/program/queries.sql.

  Step 2: User queries — remove institution_id

  In internal/features/user/queries.sql:

  Remove the GetUserWithInstitution query (lines 43-52):

  -- name: GetUserWithInstitution :one SELECT  u.*,  i.id as institution_id,  ...

  Remove the UpdateUserInstitution query (lines 65-69):

  -- name: UpdateUserInstitution :one UPDATE users SET institution_id = $2, updated_at = NOW() WHERE id = $1 RETURNING *;

  Remove institution_id from CreateUser query. Change line 55 from:

  INSERT INTO users (email, name, password_hash, institution_id, is_platform_admin) VALUES ($1, $2, $3, $4, $5)

  to:

  INSERT INTO users (email, name, password_hash, is_platform_admin) VALUES ($1, $2, $3, $4)

  Step 3: Institution queries — add email domain verification query

  Add to internal/features/institution/queries.sql:

  -- name: GetInstitutionByEmailDomain :one -- Verifies an email's domain belongs to a specific institution. -- Used by SSO handlers to replace user.institution_id check. SELECT i.* FROM institutions i JOIN institution_domains d ON d.institution_id = i.id WHERE LOWER(d.domain) = $1 AND i.id = $2;

  Step 4: Commit

  git add internal/features/program/queries.sql internal/features/user/queries.sql internal/features/institution/queries.sql git commit -m "queries: remove institution_id from users, add domain verification query"

  ---

  Task 3: Update proto and regenerate code

  Files: - Modify: proto/program/v1/program.proto - Run: make generate

  Step 1: Add institution_id to Program proto

  In proto/program/v1/program.proto, add institution_id to the Program message:

  message Program {  string id = 1;  string name = 2;  string slug = 3;  google.protobuf.Timestamp created_at = 4;  google.protobuf.Timestamp updated_at = 5;  string timezone = 6;  string institution_id = 7; }

  Add institution_id to CreateProgramRequest:

  message CreateProgramRequest {  string name = 1;  string slug = 2;  string institution_id = 3; }

  Step 2: Regenerate all code

  Run: make generate

  This regenerates: - gen/ — protobuf Go code - internal/db/sqlc/ — sqlc Go code

  After regeneration, sqlc.Program.InstitutionID changes from pgtype.UUID to uuid.UUID (non-nullable), and sqlc.User no longer has InstitutionID. sqlc.CreateUserParams no longer has InstitutionID.

  Step 3: Commit

  git add proto/ gen/ internal/db/sqlc/ git commit -m "proto: add institution_id to Program, regenerate code"

  ---

  Task 4: Update program service and models

  Files: - Modify: internal/features/program/service.go - Modify: internal/features/program/models.go

  Step 1: Update CreateProgram handler

  In internal/features/program/service.go, add institution_id validation and pass it to the query.

  Add validation after the slug check:

  if strings.TrimSpace(req.Msg.InstitutionId) == "" {  return nil, apperrors.InvalidArgumentError("institution_id", "Institution ID is required.") }

  Parse the UUID:

  institutionID, parseErr := id.ParseUUID(req.Msg.InstitutionId, "institution ID") if parseErr != nil {  return nil, parseErr }

  Update the CreateProgramParams to pass it:

  org, err := queries.CreateProgram(ctx, sqlc.CreateProgramParams{  Name: req.Msg.Name,  Slug: req.Msg.Slug,  InstitutionID: institutionID, })

  Step 2: Update models.go

  In internal/features/program/models.go, add InstitutionId to both converter functions.

  In dbOrgToProto:

  func dbOrgToProto(org sqlc.Program) *programv1.Program {  return &programv1.Program{  Id: org.ID.String(),  Name: org.Name,  Slug: org.Slug,  CreatedAt: timestamppb.New(org.CreatedAt.Time),  UpdatedAt: timestamppb.New(org.UpdatedAt.Time),  Timezone: org.Timezone,  InstitutionId: org.InstitutionID.String(),  } }

  In dbOrgWithStatsToProto, add InstitutionId: row.InstitutionID.String() to the Program struct.

  Step 3: Commit

  git add internal/features/program/ git commit -m "feat: require institution_id when creating programs"

  ---

  Task 5: Update testutil and test helper

  Files: - Modify: internal/testutil/testutil.go

  Step 1: Add CreateInstitution helper

  Add a helper function to internal/testutil/testutil.go:

  // CreateInstitution creates a test institution. // Returns the created institution for use in test setup. func CreateInstitution(ctx context.Context, t *testing.T, queries *sqlc.Queries, name, slug string) sqlc.Institution {  t.Helper()  institution, err := queries.CreateInstitution(ctx, sqlc.CreateInstitutionParams{  Name: name,  Slug: slug,  })  if err != nil {  t.Fatalf("CreateInstitution: failed to create institution: %v", err)  }  return institution }

  Step 2: Remove InstitutionID from CreateUserWithProgram

  In CreateUserWithProgram, remove InstitutionID: pgtype.UUID{} from the CreateUserParams. After codegen, this field no longer exists on the struct.

  Step 3: Commit

  git add internal/testutil/testutil.go git commit -m "test: add CreateInstitution helper, remove institution_id from user creation"

  ---

  Task 6: Update all test files — CreateProgram calls need institution

  Every test file that calls queries.CreateProgram(ctx, sqlc.CreateProgramParams{...}) with InstitutionID: pgtype.UUID{} must:

  1. Create an institution first using testutil.CreateInstitution (or queries.CreateInstitution directly)
  2. Pass InstitutionID: institution.ID instead of pgtype.UUID{}

  Every test file that calls queries.CreateUser(ctx, sqlc.CreateUserParams{...}) with InstitutionID: pgtype.UUID{} must remove the InstitutionID field (it no longer exists on the struct).

  Files to modify (every file from the grep results):

  Programs — need institution + remove from user creation: - internal/features/program/service_test.go (13 occurrences) - internal/features/user/service_test.go (10 occurrences) - internal/features/user/integration_test.go - internal/features/user/flows_test.go - internal/features/user/getcurrentuser_test.go - internal/features/membership/service_test.go - internal/features/resident/service_test.go - internal/features/rotation/service_test.go - internal/features/rotation/queries_test.go - internal/features/rotationschedule/service_test.go - internal/features/rotationscheduleblock/service_test.go - internal/features/rotationschedulepreference/service_test.go - internal/features/rotationscheduleconstraint/service_test.go - internal/features/rotationschedulesolver/snapshot_test.go - internal/features/liverotationschedule/service_test.go - internal/features/tag/service_test.go - internal/features/site/service_test.go - internal/features/shift/service_test.go - internal/features/calltype/service_test.go - internal/features/callschedule/service_test.go - internal/features/callshifttemplate/service_test.go - internal/features/callshifttemplaterel/service_test.go - internal/features/call/postgres/template_repository_test.go - internal/features/call/postgres/shift_repository_test.go - internal/auth/interceptor_test.go - internal/authz/authz_test.go

  Pattern for each test file:

  Most test files have a setup section that creates a program. The pattern change is:

  Before:

  org, err := queries.CreateProgram(ctx, sqlc.CreateProgramParams{  Name: "Test Org",  Slug: "test-org",  InstitutionID: pgtype.UUID{}, })

  After:

  institution := testutil.CreateInstitution(ctx, t, queries, "Test Institution", "test-inst") org, err := queries.CreateProgram(ctx, sqlc.CreateProgramParams{  Name: "Test Org",  Slug: "test-org",  InstitutionID: institution.ID, })

  And remove InstitutionID: pgtype.UUID{} from all CreateUserParams structs (the field no longer exists).

  For files with multiple CreateProgram calls (e.g., program/service_test.go), create the institution once in a test helper and reuse it. Since each test gets an isolated database, institution slugs won’t conflict.

  Step: Run tests to verify

  Run: make test-go Expected: All tests pass

  Step: Commit

  git add internal/ git commit -m "test: update all tests to create institution before program"

  ---

  Task 7: Update SSO handlers — verify institution via email domain

  Files: - Modify: internal/sso/saml_handler.go - Modify: internal/sso/oidc_handler.go - Modify: internal/sso/saml_integration_test.go

  Step 1: Update SAML handler

  In internal/sso/saml_handler.go, replace the institution mismatch check (around line 397-408).

  Before:

  // Verify user belongs to the institution that initiated SAML flow. if !user.InstitutionID.Valid || uuid.UUID(user.InstitutionID.Bytes) != institutionID {  slog.Warn("SAML ACS: user institution mismatch",  slog.String("user_id", user.ID.String()),  slog.String("expected_institution", institutionID.String()),  slog.String("remote_addr", r.RemoteAddr),  )  h.redirectWithError(w, r, "institution_mismatch")  return }

  After:

  // Verify user's email domain belongs to the institution that initiated SAML flow. // This prevents cross-institution authentication if IdPs are shared between institutions. emailDomain := extractEmailDomain(email) _, err = queries.GetInstitutionByEmailDomain(ctx, sqlc.GetInstitutionByEmailDomainParams{  Lower: emailDomain,  ID: institutionID, }) if err != nil {  slog.Warn("SAML ACS: user email domain does not match institution",  slog.String("email_domain", emailDomain),  slog.String("expected_institution", institutionID.String()),  slog.String("remote_addr", r.RemoteAddr),  )  h.redirectWithError(w, r, "institution_mismatch")  return }

  Add a helper function (or reuse from user package if importable):

  func extractEmailDomain(email string) string {  parts := strings.Split(email, "@")  if len(parts) != 2 || parts[1] == "" {  return ""  }  return strings.ToLower(parts[1]) }

  Step 2: Update OIDC handler

  Same pattern in internal/sso/oidc_handler.go around line 337-345. Replace the user.InstitutionID check with the same email domain verification.

  Step 3: Update SSO tests

  In internal/sso/saml_integration_test.go, remove InstitutionID from CreateUserParams calls. The test users need institution domains set up to pass the new check instead.

  Lines 96-98 — change from:

  InstitutionID: pgutil.UUIDFromValue(institution.ID),

  to: (remove the line, and ensure the test creates an institution domain for the user’s email domain)

  Lines 463-465 — same pattern for cross-institution test.

  Step 4: Run tests

  Run: make test-go Expected: All tests pass

  Step 5: Commit

  git add internal/sso/ git commit -m "refactor: SSO handlers verify institution via email domain instead of user column"

  ---

  Task 8: Update seed data

  Files: - Modify: cmd/seed/main.go

  Step 1: Create default institution for seed programs

  Add a default institution creation in the run() function before programs are created. Something like:

  defaultInstitution, err := getOrCreateInstitution(ctx, qtx, "Default Institution", "default", "", "")

  Note: getOrCreateInstitution already exists in the seed file. The SSO provider can be empty/nil for a non-SSO institution.

  Step 2: Pass institution ID to program creation

  Change all CreateProgramParams in seed from InstitutionID: pgtype.UUID{} to InstitutionID: defaultInstitution.ID.

  Step 3: Remove institution_id from user creation

  Remove InstitutionID: pgtype.UUID{} from all CreateUserParams in seed (the field no longer exists).

  For SSO seed users, remove InstitutionID: pgutil.UUIDFromValue(institutionID) from the createSSOUser function.

  Step 4: Commit

  git add cmd/seed/main.go git commit -m "seed: create default institution for programs, remove institution_id from users"

  ---

  Task 9: Run full validation

  Step 1: Reset local database

  Run: make db-nuke

  (Migration changed, pgmigrate won’t re-run it without reset.)

  Step 2: Run full check

  Run: make fix && make verify

  Expected: All linters pass, all tests pass, type checking passes.

  Step 3: Fix any remaining compilation errors

  The codegen will have removed InstitutionID from User-related structs. If any file still references it, fix the compilation error.

  ---

  Task 10: Create PR

  git checkout -b feat/required-institutions git push -u origin HEAD gh pr create --title "Make institution_id required on programs, remove from users" --body "..."

• Soft Targets / Fairness Constraints — Future Design Notes
• Plans - Guava Docs

  Plans

  Design documents for Guava features.

  Documents

  • call-scheduling-domain.md - DDD architecture for call scheduling
  • shift-service.md - ShiftService RPC layer design
  • manual-call-schedule-ui.md - Calendar UI for manual shift management

  Related

  • Scheduling Principles - Core architectural principles
  • Call Scheduling Reference - Domain terminology