# airstrike/iced_receipts architecture

> Architecture diagram of the GitHub repository airstrike/iced_receipts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/airstrike/iced_receipts
- Repository: https://github.com/airstrike/iced_receipts

## Overview

##### Project Type and Purpose
- This is a **desktop GUI application** (no separate frontend/backend) built in Rust using the Elm-style MVU pattern with the `iced` framework.
- Purpose: manage a list of sales (“receipts”) with multiple screens (list, show, edit), unified state, and an `Action` API to compose in-app instructions and iced tasks.

##### File Structure
- src/main.rs: Defines the `App` struct, `view()`, and top-level `update()` that drives the MVU loop.
- src/action.rs: Defines `Action<Instruction, Message>` type (optional `Instruction` + iced `Task<Message>`).
- src/list.rs: `List` screen module (`view()` + `update()`).
- src/sale/edit.rs & sale/show.rs: Two modes of `Sale` screen, each with its own `view()` + `update()`.
- src/sale.rs: Shell module that routes `Message::Show` and `Message::Edit` to the appropriate submodule.

##### README for Insights
- Emphasis on unidirectional flow: `view()` → Messages → `update()` → `Action` → tasks → new Messages.
- `Action` composes pure instructions (app‐level commands) with runtime tasks (e.g., focusing an input).
- `App::update` calls `perform(instruction)` to turn an `Instruction` into a `Task<Message>`, then chains it with the `Action`’s task.

##### Main Components & Their Interactions
a. GUI / iced Runtime
- Hosts the event loop, scheduler, and renderer.
- Invokes `App::view()` to build the UI, and `App::update()` on incoming `Message`s or completed tasks.
b. App (Top-Level)
- Holds global state (list of sales, which screen is active, etc.).
- view(): delegates to active screen’s `view()`, tagging widgets with `Message` variants.
- update(msg):
- Pattern-matches on `Message` (e.g. `Message::Sale(id, msg)`)
- Delegates to screen-specific `update()`, yielding an `Action<Instruction, Message>`
- If `action.instruction` is `Some(instr)`, calls `perform(instr) -> Task<Message>`
- Chains `instruction_task.chain(action.task)` and returns it to iced.
c. Screens (List, Show, Edit)
- Each defines its own `Message` enum, `view()`, and `update()` returning `Action`.
- Example: in `sale/show`, `update()` on `StartEdit` returns `Action::instruction(StartEdit).with_task(focus_next())`.
d. Action API
- Type: `struct Action<Instruction, Message> { instruction: Option<Instruction>, task: Task<Message> }`
- Methods:
- `Action::instruction(instr)` sets an instruction, defaulting task to `Task::none()`.
- `.with_task(task)` attaches a runtime task.
- `.map_instruction(...)` / `.map(...)` to rewrap inner messages/instructions at the App level.
e. perform(instruction)
- Converts an `Instruction` into a `Task<Message>` by performing side effects (e.g. I/O, focus).
- Returns a future that, when resolved, yields a new `Message` fed back to `App::update()`.

##### Architectural Patterns & Design Principles
- **MVU (Model-View-Update)**: Strict unidirectional data flow.
- **Action Monad**: Composes pure “instructions” and asynchronous “tasks” without exploding enum variants.
- **Modularity**: Screens are isolated modules, each owning its own state, `Message`, `view()`, and `update()`.
- **Chaining Tasks**: Ensures instructions can spawn tasks (e.g. UI focus), with results feeding back as messages.

##### Detail
- Clearly separate `Instruction` (app‐level command) from `Task<Message>` (async runtime work).
- How screens scoping is handled via `Message::Sale(id, msg)` and `.map_instruction` / `.map`.
- Chaining step: `instruction_task.chain(action.task)`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Runtime
    User["User Input"]:::ui
    Runtime["iced Runtime\n(Event Loop / Scheduler / Renderer)"]:::runtime

    %% Core MVU App
    App["App\n(state, view(), update())"]:::state

    %% Screens
    subgraph "Screens"
        List["List Screen\n(view()/update())"]:::state
        SaleShell["Sale Shell\n(routes Show/Edit)"]:::state
        subgraph "Sale Screens"
            SaleShow["Sale Show Screen\n(view()/update())"]:::state
            SaleEdit["Sale Edit Screen\n(view()/update())"]:::state
        end
    end

    %% Action API and perform()
    ActionAPI["Action API\n(Instruction, Task<Message>)"]:::action
    Perform["perform()\nInstruction → Task<Message>"]:::runtime

    %% Data Flow
    User -->|"Input Events"| Runtime
    Runtime -->|"invokes update(Message)"| App
    App -->|"delegates to Screen.update()"| List
    App -->|"routes Sale messages"| SaleShell
    SaleShell -->|"maps to submodule"| SaleShow
    SaleShell -->|"maps to submodule"| SaleEdit
    List -->|"returns Action"| ActionAPI
    SaleShow -->|"returns Action"| ActionAPI
    SaleEdit -->|"returns Action"| ActionAPI
    ActionAPI -->|"has instruction?"| Perform
    ActionAPI -->|"has Task<Message>"| Runtime
    Perform -->|"returns Task<Message>"| Runtime
    Runtime -->|"on Task complete\nyields Message"| App
    App -->|"view() builds UI"| Runtime

    %% Click Events
    click App "https://github.com/airstrike/iced_receipts/blob/master/src/main.rs"
    click ActionAPI "https://github.com/airstrike/iced_receipts/blob/master/src/action.rs"
    click List "https://github.com/airstrike/iced_receipts/blob/master/src/list.rs"
    click SaleShell "https://github.com/airstrike/iced_receipts/blob/master/src/sale.rs"
    click SaleShow "https://github.com/airstrike/iced_receipts/blob/master/src/sale/show.rs"
    click SaleEdit "https://github.com/airstrike/iced_receipts/blob/master/src/sale/edit.rs"

    %% Styles
    classDef ui fill:#add8e6,stroke:#000
    classDef state fill:#98fb98,stroke:#000
    classDef action fill:#ffff99,stroke:#000
    classDef runtime fill:#dda0dd,stroke:#000
```
