# Architecture

## Core Crates

### ui

Shared UI layer used by both firmware and simulator.

Responsibilities:

- application views
- layout logic
- widget composition
- UI state
- event abstraction

The goal is to keep most UI logic portable between simulator and hardware.


### firmware

The firmware crate targets **PineTime hardware**.

Responsibilities:

- hardware initialization
- display driver integration
- BLE stack integration
- input and touch handling
- power management
- system services


### simulator

Desktop environment used for development.

Responsibilities:

- run UI without hardware
- simulate events and inputs
- allow rapid UI iteration
- reduce flashing cycles


## Rendering Model

The expected rendering stack is:

```
     ratatui
        ↓
    mousefood
        ↓
 embedded-graphics
        ↓
  display driver
```

Simulator rendering will use a different backend but share the UI layer.


## Simulator Role

The simulator exists to improve development speed.

It should help with:

- UI development
- event testing
- application logic

However:

Simulator correctness does **not guarantee hardware correctness**.

Timing, memory limits, BLE behavior, and display performance must still be tested on the real device.