POS Design-Decision Map

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.