# Workflow Analysis

## Workflow States

### Reconciliation

Observed controller states in `src/odin_lunchtab/gui_controller.py`:

| State | Meaning | Entry trigger | Exit trigger |
| --- | --- | --- | --- |
| `EMPTY` | Required files are not selected. | App start or incomplete input selection. | Select both Odin and Lunchtab files. |
| `READY_TO_VALIDATE` | Files are selected but not validated. | Select both files or change profile. | Begin validation. |
| `VALIDATING` | Input validation is in progress. | Operator validates. | Validation succeeds or fails. |
| `VALID` | Inputs passed validation and can be processed. | Validation success. | Begin processing or change input/profile. |
| `PROCESSING` | Reconciliation outputs are being written. | Operator starts process. | Processing succeeds or fails. |
| `COMPLETE` | Run folder and outputs are available. | Processing success. | Change input/profile for another run. |
| `ERROR` | Validation or processing failed. | Exception surfaced to controller. | Correct inputs and retry. |

### Manual Reconciliation Review

Observed states:

| State | Meaning |
| --- | --- |
| `EMPTY` | Original or edited transfer is not selected. |
| `READY_TO_REVIEW` | Both transfer files are selected. |
| `REVIEWING` | Delta audit is in progress. |
| `COMPLETE` | Review finished with PASS or REVIEW status. |
| `BLOCKED` | Review found invalid manual amounts. |
| `ERROR` | Review failed structurally or unexpectedly. |

### InitialBalances Transfer

Observed states:

| State | Meaning |
| --- | --- |
| `EMPTY` | Transfer or InitialBalances file is not selected. |
| `READY_TO_VALIDATE` | Both CSV files are selected. |
| `VALIDATING` | Validation and optional preflight are running. |
| `VALID` | Inputs can be formally processed. |
| `PROCESSING` | Transfer, audit, and manifest generation are running. |
| `COMPLETE` | Clean import was produced. |
| `BLOCKED` | Audit artifacts were produced but import was withheld. |
| `ERROR` | Workflow failed outside expected blocked-run path. |

## Decision Points

| Decision point | Decision rule | Evidence quality |
| --- | --- | --- |
| Are source files usable? | File type, existence, headers, encodings, and required profile fields must validate. | Observed |
| Is a reconciliation match safe? | Unique target, compatible names, no conflicting rules, no duplicate source/target. | Observed |
| Should an exception appear in manual review? | All exception reasons except `no Lunchtab match` appear in the focused manual-review file. | Observed |
| Can candidate selection be applied? | Candidate must be actionable, transfer row must still match, and selected row must have blank current balance. | Observed |
| Is manual reconciliation ready for downstream use? | Invalid manual amounts block; risky edits require review; normal manual resolutions pass with audit. | Observed |
| Can InitialBalances import be published? | No blocking exceptions and control totals pass. | Observed |

## Failure Paths

- Invalid file extension or missing source file stops validation.
- Missing required columns stop validation.
- Unsupported or corrupted CSV encoding stops parsing.
- Malformed Odin rows are reported and excluded from valid source control totals.
- Duplicate or ambiguous matches are quarantined rather than guessed.
- Audit-control failures raise runtime errors and prevent a successful run.
- Manual reconciliation structural mismatch stops review.
- Invalid manual amount blocks downstream use.
- InitialBalances exceptions produce blocked audit artifacts and omit the processed import file.

## Notifications And Feedback

Observed:

- Desktop UI status text changes across validation, processing, success, blocked, and error phases.
- Completion screens expose buttons to open result folders and key reports.
- Run summaries provide operator-readable next actions.
- Candidate viewer supports actionable-only and ambiguous-only filtering and can export checklists.

Inferred:

- There is no external notification channel such as email or ticketing; staff review is local and file-based.

## Workflow Strengths

- Strong separation between automated safe matches and human-reviewed exceptions.
- Clear blocked-run behavior for InitialBalances.
- Repeatable profile-driven matching for venue differences.
- Audit evidence for matches, exceptions, manual edits, and control totals.
- Synthetic sandbox data supports training and non-live verification.

## Workflow Constraints

- The process still depends on staff obtaining correct exports from Odin and Lunchtab.
- Profile quality directly affects match rate and exception volume.
- Candidate reports and proposed transfers are advisory; final operational approval remains manual.
- The application is file-based rather than integrated directly with source or destination systems.