Design Decisions

Design goals

• Precise parameter to cell mapping for accurate report rendering
• Multi tenant support with lab specific overrides and safe defaults
• Fast reads at render time and safe auditable writes at admin time
• Simple and maintainable API surface for UI integration

Data model and rationale

• Cells
  Acts as a reusable palette of visual definitions including name, background color, foreground color, and default key.
  This keeps styling centralized and avoids coupling with mappings or reports.

• CellCounterMappings
  Maps the exact target using the tuple
  lab, test, report_format_index, report_format_order, key
  This ensures deterministic resolution and removes ambiguity.

• AllTests and ReportFormat
  Remain the source of truth for test metadata and report parameter identity.
  Using index and order allows targeting the same logical parameter across multiple report formats while preserving display order.

API and operational choices

• Cell Counter Mapping API supports bulk upsert and bulk replace for efficient mapping management
• Bulk operations are wrapped in transactions to ensure atomic updates
• Upsert semantics align with common workflows such as copying defaults and applying lab specific changes
• Replace operation is explicit and intended for full reconfiguration scenarios

Safety validation and auditability

• Unique composite keys enforce database level consistency
• Timestamps created_at and updated_at track lifecycle changes
• is_disable flag supports soft lifecycle control
• API level validation ensures key normalization and valid cell references

UX and admin ergonomics

• Supports copy from default workflows using lab null defaults
• Enables intuitive lab specific overrides
• Admin UI can display Cells as a visual palette for quick selection and preview

Architecture diagram