SPB Git

Repository Public License

workflows.md 7.0 KB 121 lines markdown

1<!--2ORIX Scan3File: docs/architecture/workflows.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# ORIX Actions910ORIX Actions is a small workflow engine: an input source followed by an ordered list of steps, each of which calls the same11engine functions the rest of the app uses. The model and the engine are in `Packages/ORIXKit/Sources/ORIXKit/Actions/` and12have no dependency on the interface.1314## Model1516`Workflow`: `id`, `name`, `symbol` (SF Symbol name), `input`, `steps`, `presetKey` (set for built-in presets, which are17read-only; duplicating one makes an editable copy).1819`WorkflowInput`: `scan`, `photos`, `files`, `library`.2021`ActionStep`: `id`, `kind`, and one field per parameter (`filter`, `recognition`, `preset`, `searchable`, `pattern`,22`folderName`). Each kind reads the parameters it needs.2324| `ActionKind` | What it does | Parameters |25|---|---|---|26| `autoCrop` | `DocumentProcessor.autoCrop`: detects the page outline on image pages that have no crop | none |27| `deskew` | `DocumentProcessor.deskew`: straightens image pages from their text baseline | none |28| `enhance` | Sets the filter of every image page (shadow reduction on, except for Original) | `filter` |29| `recognizeText` | `DocumentProcessor.recognize` with the app's languages | `recognition` mode |30| `rename` | Renames the document from a pattern | `pattern` with `{title}`, `{date}` (yyyy-MM-dd), `{time}` (HH.mm), `{pages}` |31| `moveToFolder` | Files the document in a folder, created if needed | `folderName` |32| `markFavorite` | Adds the document to Favourites | none |33| `exportPDF` | `DocumentProcessor.exportPDF` | `preset`, `searchable` |34| `exportText` | Writes the recognized text as a `.txt` file | none |35| `exportTables` | Writes one CSV per detected table | none |3637`Workflow.validationIssues` reports `noSteps`, `missingFolder` (a `moveToFolder` step with an empty name) and38`emptyPattern` (a `rename` step with an empty pattern). The builder shows these next to the step and disables Run.3940User workflows are stored as `WorkflowRecord` (JSON payload), so the model can evolve without a SwiftData schema migration.4142## Presets4344Defined in `Workflow.presets`, with stable identifiers:4546| Preset | Input | Steps |47|---|---|---|48| Scan to PDF | Scan | Enhance (Colour) → Create PDF (Balanced, no text layer) |49| Scan to Searchable PDF | Scan | Enhance (Colour) → Recognize Text (Automatic) → Create PDF (Balanced, searchable) |50| Receipt Archive | Scan | Enhance (Greyscale) → Recognize Text → Rename `Receipt {date} {time}` → Move to Folder "Receipts" |51| Document Cleanup | Photos | Detect Edges → Straighten → Enhance (Black & White) |52| Book Scanner | Scan | Straighten → Enhance (Greyscale) → Recognize Text (Accurate) → Create PDF (Balanced, searchable) |53| Extract Text | Photos | Detect Edges → Recognize Text → Export Text |54| Extract Tables | Photos | Detect Edges → Straighten → Recognize Text (Accurate) → Export Tables |55| Compress PDF | Files | Create PDF (Small File Size, searchable) |5657## Engine5859```mermaid60flowchart TD61    Start["WorkflowEngine.run(workflow, on: documentID)"] --> Valid{"validationIssues empty?"}62    Valid -- no --> Throw["throw"]63    Valid -- yes --> Next{"next step"}64    Next --> Cancel{"task cancelled?"}65    Cancel -- yes --> Cancelled["throw ORIXError.cancelled"]66    Cancel -- no --> Exec["execute step<br/>progress 0…1"]67    Exec -- done or nothing to do --> Record["append StepOutcome"]68    Exec -- error --> Fail["outcome: failed<br/>remaining steps: skipped"]69    Record --> Next70    Fail --> Result71    Next -- no more steps --> Result["WorkflowResult<br/>outcomes, artifacts, newTitle, folderName, markFavorite"]72```7374- **Sequential.** Steps run in order on one document. `WorkflowProgress` carries the step index, the step count, the kind75  and the fraction inside the step; `overall` combines them.76- **Outcomes.** Every step produces a `StepOutcome` with a status (`done`, `nothingToDo` with a reason such as77  `noOutlineFound`, `alreadyStraight`, `alreadyRecognized`, `noTextFound`, `noTablesFound`, `failed`, `skipped`), a factual78  detail (pages changed, lines read, file name and size, files written, new title, folder) and its duration.79- **Failure.** A step that throws is recorded as `failed`; the run stops and the remaining steps are recorded as `skipped`.80  Steps that already ran keep their effect. Because each step saves a complete manifest, the document is valid at every81  point.82- **Cancellation.** The engine checks before each step and the engine functions check between pages; a cancelled run throws83  `ORIXError.cancelled`.84- **Text when needed.** `exportText` and `exportTables` call `recognize` first, as does `exportPDF` when `searchable` is on.85  `recognize` skips pages whose text is already up to date, so an explicit Recognize Text step earlier in the workflow is86  not repeated.87- **Library changes are returned, not applied.** The engine does not touch the SwiftData index. `moveToFolder` and88  `markFavorite` set `WorkflowResult.folderName` and `markFavorite`; `rename` saves the manifest and also reports89  `newTitle`. The caller applies them.90- **Artifacts.** Export steps append file URLs to `WorkflowResult.artifacts`, in step order.9192`WorkflowEngine.resolve(pattern:title:pageCount:now:timeZone:)` expands rename tokens with a fixed POSIX locale so names do93not depend on the device's language.9495## In the app9697`WorkflowLauncher.start` (`App/Sources/Actions/ActionsView.swift`) obtains the input: the scanner (or Photos when the98device has no camera), the Photos picker, the file importer, or `DocumentChooser` for library documents. Capture ends in99`AppModel.receive` with a `.workflow` destination, which creates the document and sets `AppModel.workflowRun`.100101`WorkflowRunView` (`App/Sources/Actions/WorkflowRunView.swift`) executes the run:102103- one document after another for a batch (`WorkflowRun.documentIDs`), waiting for any recognition already in progress on104  that document;105- live status per step, a progress bar across the batch, and Cancel;106- after each document it applies the returned library changes through `LibraryIndex` and calls `AppModel.didChange`;107- at the end it offers the artifacts to the share sheet and, for a single document, a button to open it.108109The run holds a `BackgroundWork` assertion so it can finish if the app is briefly sent to the background.110111`WorkflowEditorView` is the visual builder: name, icon, input, an ordered list of step cards with their parameters, Add112Step, reordering and deletion in edit mode. Changes are saved to the `WorkflowRecord` as they are made.113114## Reuse by other ORIX apps115116The engine pattern is independent of documents in three places that another app can copy: a `Codable` step with a `kind`117and flat parameters, an executor that returns per-step outcomes plus changes for the caller to apply, and validation that118lives in the model. Today `ActionKind` and `WorkflowEngine.execute` are specific to `DocumentProcessor`; they are not yet119generic over a step protocol. Making the engine generic is the work needed before a second app shares the code rather than120the design.121
Files main
Menu

Theme