# Design Decision Map

## Purpose

Show how implemented design choices support business requirements and where design rationale needs stakeholder confirmation.

## Inputs

- `README.md`
- `src/odin_lunchtab/workflow.py`
- `src/odin_lunchtab/managed.py`
- `src/odin_lunchtab/manual_reconciliation.py`
- `src/odin_lunchtab/initial_balances.py`
- `src/odin_lunchtab/profiles.py`
- `src/odin_lunchtab/exception_candidates.py`
- `src/odin_lunchtab/candidate_viewer.py`
- `src/odin_lunchtab/gui_controller.py`
- Tests under `tests/`

## BA Activities

- Analyze requirements and define design options.
- Manage requirements lifecycle.
- Evaluate solution.

## Techniques Applied

- Decision analysis: separated design choice, rationale, alternatives, and tradeoffs.
- Interface analysis: mapped each design to input/output artifacts and state transitions.
- Risk analysis: linked design choices to operational and control risks.

## Decision Trace

| Decision ID | Implemented Design Decision | Business Rationale | Supported Requirements | Tradeoff | Evidence Quality | Validation Need |
| --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | Write to new output files and managed run folders instead of altering source files. | Protect source exports and support reruns/audit. | REQ-001, REQ-014, REQ-015 | Requires operators to manage generated outputs. | Observed | Confirm output retention expectations. |
| DEC-002 | Quarantine unsafe matches instead of applying best guesses. | Prioritize financial and identity accuracy over maximum automation. | REQ-003, REQ-005, REQ-008 | Creates manual review workload. | Observed | Confirm risk appetite for false negatives versus false positives. |
| DEC-003 | Keep matching metadata out of Lunchtab upload CSV and place it in audit reports. | Preserve import compatibility while retaining trace evidence. | REQ-002, REQ-006 | Operators must consult separate audit files. | Observed | Confirm Lunchtab import constraints. |
| DEC-004 | Use configurable matching profiles rather than hard-coded venue-specific logic. | Support different venue identifiers without code release. | REQ-004 | Adds profile governance needs. | Observed | Confirm who owns profile approval and change control. |
| DEC-005 | Require name validation for crosswalk and identifier matches. | Avoid applying balances to the wrong person when identifiers collide or stale mappings exist. | REQ-003, REQ-005 | Legitimate matches with name differences are sent to exceptions. | Observed | Confirm acceptable name-matching tolerance. |
| DEC-006 | Treat candidate reports as advisory and require explicit selection or staff edit. | Keep human accountability for unresolved cases. | REQ-008, REQ-009, REQ-010 | More staff action is required before InitialBalances. | Observed | Confirm candidate workflow is the desired operating model. |
| DEC-007 | Allow proposed transfer creation from validated candidate selections while preserving original transfer. | Reduce manual edit effort while retaining auditability. | REQ-009 | Creates another intermediate artifact that must be governed. | Observed | Confirm proposed transfer naming and approval process. |
| DEC-008 | Audit edited transfer files before InitialBalances. | Detect risky changes before balances are imported into Lunchtab. | REQ-010, REQ-011 | Adds an extra workflow step after manual edits. | Observed | Confirm whether all manual edits must pass review before import. |
| DEC-009 | Make InitialBalances preflight non-writing and formal run writing. | Let operators see blockers before creating official output evidence. | REQ-011, REQ-013 | Requires distinction between preview and formal run. | Observed | Confirm whether preflight results should be retained. |
| DEC-010 | Omit processed InitialBalances import when any blocker exists. | Avoid partial imports when financial controls do not pass. | REQ-013 | Blocks all output even if some families are safe. | Observed | Confirm all-or-nothing import policy. |
| DEC-011 | Use staged output folders then rename into timestamped run folders. | Avoid partially published run folders. | REQ-014 | Requires cleanup handling for failed staging. | Observed | Confirm filesystem and network-share assumptions. |
| DEC-012 | Store manifests with hashes, filenames, counts, and generated artifacts. | Support audit trail without storing row-level private data. | REQ-015 | Hashes may not be meaningful to all operators. | Observed | Confirm privacy and audit policy acceptance. |
| DEC-013 | Model desktop flows through explicit controller phases. | Prevent invalid operations and stale results. | REQ-016 | GUI code must keep controller and display states synchronized. | Observed | Confirm UI messages and phase language with operators. |
| DEC-014 | Use synthetic sandbox packs and verification presets. | Support testing without live student/family data. | REQ-018 | Synthetic data may miss real-world edge cases. | Observed | Confirm fixture scenarios against known operational cases. |
| DEC-015 | Package as a Windows per-user desktop app. | Fit non-technical operator deployment without admin rights or Python. | REQ-019 | Release validation extends beyond unit tests. | Observed | Confirm target deployment environment and support model. |

## Traceability

Each design decision maps back to at least one requirement in `requirements-design-traceability.md`. Decisions DEC-002, DEC-005, DEC-010, and DEC-012 are high-control choices and should receive explicit stakeholder approval because they define the application's risk posture.

## Validation Needs

- Product/operations should validate DEC-002 and DEC-010 as business policy, not only implementation behavior.
- Data owner or compliance reviewer should validate DEC-012.
- Release owner should validate DEC-015 against actual clean-machine installation and upgrade evidence.