# Peach — frontend architecture

Peach follows the Autoreceptive Flutter architecture (`Frontend/Receptive` as
the reference base). Everything below is enforced convention, not suggestion —
new code that ignores it will look wrong next to the rest.

## 1. Stack

- **Flutter**, state management **`stacked`** (MVVM) via `ViewModelBuilder.reactive`.
- **Transport:** SSH/SFTP (`dartssh2`) — Peach talks to servers, not an HTTP API.
- **Storage:** `shared_preferences` for config, `flutter_secure_storage` (OS
  keystore) for passwords.
- **Codegen:** Mason brick for screens (§6).
- Core idea: **every screen is 4 files**; **one** `ParentViewModel` centralises
  loading/error/reachability; **one** `AppDataManager` is the single data gateway.

## 2. Folder structure (`lib/Peach/`)

```
lib/Peach/
  about/                     # models (one class per file, named after the class)
    external/data/           #   what comes back FROM a server (Docker, Kafka, Redis, Health…)
    external/initial/        #   what we send TO a server (SystemdSpec)
    internal/application/    #   app-owned models + enums (ServerProfile, ServiceConfig,
                             #   DeploymentRecord, StepTracker, NavigatorType, TextType…)
    internal/file/           #   local file work (BuildService, WebArchive, FileStorage)
  comms/                     # the wire
    ConnectComms.dart        #   abstract contract: every remote call Peach can make
    Comms.dart               #   SshService — the one implementation
  informatics/               # data gateway
    DataManager.dart         #   abstract: ConnectInternalMemory + ConnectComms + ConnectFileStorage
    AppDataManager.dart      #   the single concrete DataManager (pure delegation)
  memory/                    # local persistence
    ConnectInternalMemory.dart / InternalMemory.dart
    ConfigStore · DeploymentStore · SecretStore
  configs/                   # Navigator.dart (PeachNavigation), ThemeController.dart
  designs/                   # the design system — reuse before building
    Responsive · LogConsole · StepList · StatCard · TransferCard · OutputSheet …
    text/Text.dart (the `text()` helper)  input/InputFields.dart  navigation/SideNav.dart
  see/                       # screens — one folder per feature
    parent/ParentViewModel.dart
    <feature>/{Foo.dart, FooState.dart, ViewFoo.dart, ConnectFoo.dart}
  utils/                     # Colors · CommonUtils · Validators
main.dart
```

## 3. The 4-file screen pattern (mandatory)

| File | Role |
|---|---|
| `Foo.dart` | `StatefulWidget` shell — only creates `FooState`. |
| `FooState.dart` | `State<Foo>` — all UI + local state; **implements `ConnectFoo`**. Built with `ViewModelBuilder.reactive`. |
| `ViewFoo.dart` | `ViewModel extends ParentViewModel` — all logic; calls the `DataManager`; pushes results back through `ConnectFoo`. Never touches widgets. |
| `ConnectFoo.dart` | The callback interface between the two. |

**Wiring:**

```dart
class FooState extends State<Foo> implements ConnectFoo {
  ViewFoo? _model;

  @override
  Widget build(BuildContext context) {
    return ViewModelBuilder<ViewFoo>.reactive(
      viewModelBuilder: () => ViewFoo(context, this),
      onViewModelReady: _onReady,                          // assign + one named init
      builder: (context, viewModel, child) => Scaffold(…), // NO logic before return
    );
  }

  void _onReady(ViewFoo model) { _model = model; _initiate(); }

  Future<void> _initiate() async { _model?.loadThings(); }

  @override
  void onThingsLoaded(List<Thing> things) { setState(() => _things = things); }
}
```

## 4. `ParentViewModel` — what every ViewModel inherits

Constructed once per screen; builds the single
`AppDataManager(InternalMemory(), SshService(), FileStorage())`.

- `showLoading(text)` / `closeLoading()` — full-screen loading overlay.
- `canReach(server, retry)` — opens (or reuses) an SSH session; on failure raises
  the *server-unreachable* overlay wired to `retry` and returns `false`.
  **This is the SSH equivalent of the reference's connectivity `hasNetwork`** —
  Peach targets LAN/VPN boxes where a device-level internet check proves nothing.
- `handleError(error, retry, close, buttonName)` — the standard `catch`. Closes
  loading, then maps the failure onto a `PeachError`:

  | Failure | Result |
  |---|---|
  | `SSHAuthFailError` / `SSHAuthAbortError` | "Authentication failed" (critical) |
  | `SocketException` / `SSHStateError` | "Connection failed" — host/port/VPN hints |
  | `TimeoutException` | "Timed out" |
  | `SSHError` | "SSH error" with the raw detail as helper |
  | `FileSystemException` | "File error" — local artifact unreadable |
  | anything else | generic `PeachError` |

- `showApplicationNotification(type, title, description, drag, dismissible, close,
  {action, positiveAction})` — modal bottom sheet used for **all** confirmations
  (delete, install, clear). `positiveAction` must `Navigator.pop(context)` first.

## 5. Data layer

`DataManager` is the union of three contracts, so a screen never reaches for a
service directly:

- `ConnectComms` → `SshService` — deploy, systemd, docker, kafka, redis, files, logs.
- `ConnectInternalMemory` → `InternalMemory` — servers, deployment history, theme.
- `ConnectFileStorage` → `FileStorage` — local build, artifact read, web packaging.

Streams (`logs`, `stepStream`, `transferProgress`, `buildLogs`) are exposed as
getters on the ViewModel and subscribed to by the `State` — a stream of remote
output has no request/response shape to hand back one call at a time. Every
*command* still goes through the ViewModel.

## 6. Code generation

```
dart pub global activate mason_cli   # once, if mason is missing
mason get                            # once per clone
```

### Adding a screen

```
mason make mvvc_template   # project: Peach, screen: MyScreen
```

Generates the four files under `lib/Peach/see/myscreen/`, pre-wired with the
`Responsive` mobile/tablet/desktop split. Don't hand-scaffold them.

### Adding a persisted field

```
mason make internal_memory   # field: pinnedServers, type: List<ServerProfile>
```

Injects the getter/setter pair into all three files that have to agree —
`ConnectInternalMemory` (contract), `InternalMemory` (implementation + its
storage key) and `AppDataManager` (delegation) — handling JSON for objects and
lists, and putting secrets in the OS keystore under a random-suffixed key when
you answer yes to "is this a secret".

> **Passing a generic type on the command line:** `<` and `>` are shell
> redirection, so `--request_object "List<Foo>"` gets eaten before mason sees
> it and fails with *"The system cannot find the file specified"*. Either answer
> the interactive prompt, or pass a config file:
>
> ```
> echo '{"function_name":"pinnedServers","request_object":"List<ServerProfile>","secure":false}' > vars.json
> mason make internal_memory -c vars.json
> ```

Run it from the project root — the hook edits paths relative to there. It's
idempotent: re-running for an existing field detects the duplicate and skips.

## 7. Hard conventions

1. **No logic in `builder:` before `return`.** Derived values are state fields
   or getters, set in `_initiate()`.
2. **Named event handlers only** — `onPressed: _onSave`, never `onPressed: () => _save()`
   (a closure is fine only when it carries an argument, e.g. `() => _onDeploy(svc)`).
3. **`onViewModelReady`** assigns `_model` and calls one named `_initiate()`.
4. **Never build raw `Text`/`TextStyle`** for display copy — use `text(…)` from
   `designs/text/Text.dart` with a `TextType`.

   `TextType` picks a **font family**, not a weight — `Bold`→Sora,
   `Regular`→Urbanist, `Light`→PlusJakartaSans. Weight is an independent axis:
   pass `weight:` for a heavy *body* string rather than reaching for
   `TextType.Bold`, which would reface it in the display font.

   Three things are deliberately *not* routed through `text()`:
   Material slot children (`SnackBar(content:)`, `DropdownMenuItem(child:)`,
   `Chip(label:)`, `ListTile(title:)`) which the theme already styles;
   `fontFamily: 'monospace'` terminal content; and `SelectableText`.
5. **Never hardcode a hex colour.** Named colours live in `utils/Colors.dart`;
   brightness-aware surfaces come from `context.jp` (`JpColors`). Terminal
   surfaces use `ConsoleColors` — a fixed palette that stays dark in both
   themes, because a console doesn't invert.
6. **Reuse `designs/` before building.** Screen-only widgets are private methods
   at the bottom of that screen's `State`; anything reusable moves to `designs/`.
7. **Formatting helpers live in `utils/CommonUtils.dart`** (`formatBytes`,
   `formatCount`, `timeAgo`, `baseName`, `joinRemote`…) — never inline them.
8. **Navigation goes through `PeachNavigation`** with a `NavigatorType`;
   destinations are widget instances, not route strings. Use
   `navigateToPageWithData` when the parent must refresh on return.