v1.0.0 — Hexagonal architecture rewrite

Restructure the monolithic 252-line main.rs into a 10-crate workspace
with clean hexagonal architecture, swappable adapters, and a production-
ready deployment pipeline.

Backend architecture:
- domain: Canvas, Color/Position/PixelUpdate value objects, port traits
  (CanvasStore, CanvasPersistence, EventBroadcaster), BroadcastEvent
- application: use cases (place_pixel, get_state, save/restore snapshot,
  connect/disconnect), AppState with Arc snapshot cache
- config: AppConfig structs + ConfigSource trait
- api-types: shared DTOs, event name constants
- adapters: config-env, canvas-file, http-axum (rust-embed), socketio,
  websocket — all behind port traits, swappable via feature flags
- server: composition root with graceful shutdown (SIGTERM/SIGINT)

Frontend:
- Transport abstraction: Socket.IO and native WebSocket via VITE_TRANSPORT
- Canvas zoom/pan with mouse wheel, pinch-to-zoom, and +/- buttons
- ImageData rendering (~50x faster than fillRect loop)
- Touch support, responsive CSS scaling, mobile-friendly layout
- OG/Twitter Card meta tags for rich link previews

Production:
- Docker: musl static build on scratch — 2.73MB image
- CI workflows for Gitea and GitHub Actions (fmt, clippy, test, Docker push)
- deploy.sh for private registry
- 39 unit tests across domain and application
- Zero unwraps, zero unsafe, graceful error handling with tracing
- Periodic canvas snapshots with rotation, restored on startup
- All config via environment variables with typed defaults

crates/application/tests/common/mod.rs

@@ -0,0 +1,109 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use application::{AppState, InMemoryCanvasStore};
+use domain::ports::{
+    BroadcastReceiverInner, BroadcastSubscription, CanvasPersistence, EventBroadcaster,
+};
+use domain::{BroadcastEvent, Color, DomainError};
+
+#[derive(Clone)]
+pub struct SpyBroadcaster {
+    events: Arc<Mutex<Vec<BroadcastEvent>>>,
+}
+
+impl SpyBroadcaster {
+    pub fn new() -> Self {
+        Self {
+            events: Arc::new(Mutex::new(Vec::new())),
+        }
+    }
+
+    pub fn events(&self) -> Vec<BroadcastEvent> {
+        self.events.lock().unwrap().clone()
+    }
+
+    pub fn event_count(&self) -> usize {
+        self.events.lock().unwrap().len()
+    }
+}
+
+impl EventBroadcaster for SpyBroadcaster {
+    fn publish(&self, event: BroadcastEvent) {
+        self.events.lock().unwrap().push(event);
+    }
+
+    fn subscribe(&self) -> BroadcastSubscription {
+        BroadcastSubscription::new(Box::new(NoopReceiver))
+    }
+}
+
+struct NoopReceiver;
+
+impl BroadcastReceiverInner for NoopReceiver {
+    fn recv_boxed(&mut self) -> Pin<Box<dyn Future<Output = Option<BroadcastEvent>> + Send + '_>> {
+        Box::pin(async { None })
+    }
+}
+
+pub struct FakePersistence {
+    saved: Arc<Mutex<Vec<Vec<Color>>>>,
+    to_load: Mutex<Option<Vec<Color>>>,
+}
+
+impl FakePersistence {
+    pub fn empty() -> Self {
+        Self {
+            saved: Arc::new(Mutex::new(Vec::new())),
+            to_load: Mutex::new(None),
+        }
+    }
+
+    pub fn with_snapshot(pixels: Vec<Color>) -> Self {
+        Self {
+            saved: Arc::new(Mutex::new(Vec::new())),
+            to_load: Mutex::new(Some(pixels)),
+        }
+    }
+
+    pub fn saved_ref(&self) -> Arc<Mutex<Vec<Vec<Color>>>> {
+        self.saved.clone()
+    }
+}
+
+impl CanvasPersistence for FakePersistence {
+    fn save(&self, pixels: &[Color]) -> Result<(), DomainError> {
+        self.saved.lock().unwrap().push(pixels.to_vec());
+        Ok(())
+    }
+
+    fn load_latest(&self) -> Result<Option<Vec<Color>>, DomainError> {
+        Ok(self.to_load.lock().unwrap().clone())
+    }
+}
+
+pub fn test_state() -> (Arc<AppState>, SpyBroadcaster) {
+    test_state_sized(10, 10)
+}
+
+pub fn test_state_sized(width: u32, height: u32) -> (Arc<AppState>, SpyBroadcaster) {
+    let spy = SpyBroadcaster::new();
+    let state = AppState::new(
+        Box::new(InMemoryCanvasStore::new(width, height)),
+        Box::new(spy.clone()),
+        Duration::from_secs(10),
+    );
+    (Arc::new(state), spy)
+}
+
+pub fn test_state_no_cooldown() -> (Arc<AppState>, SpyBroadcaster) {
+    let spy = SpyBroadcaster::new();
+    let state = AppState::new(
+        Box::new(InMemoryCanvasStore::new(10, 10)),
+        Box::new(spy.clone()),
+        Duration::ZERO,
+    );
+    (Arc::new(state), spy)
+}

crates/application/tests/place_pixel.rs

@@ -0,0 +1,91 @@
+mod common;
+
+use application::canvas::place_pixel::{Command, Outcome};
+use domain::{BroadcastEvent, Color, Position};
+
+macro_rules! place {
+    ($state:expr, $user:expr, $x:expr, $y:expr, $color:expr) => {
+        application::canvas::place_pixel::execute(
+            &$state,
+            Command {
+                user_id: $user,
+                position: Position::new($x, $y),
+                color: Color::new($color),
+            },
+        )
+    };
+}
+
+#[test]
+fn successful_placement_returns_update() {
+    let (state, _) = common::test_state();
+    let result = place!(state, "user-1", 3, 4, 0xFF0000).unwrap();
+
+    let Outcome::Placed(update) = result else {
+        panic!("expected Placed outcome");
+    };
+    assert_eq!(update.position(), Position::new(3, 4));
+    assert_eq!(update.color(), Color::new(0xFF0000));
+}
+
+#[test]
+fn placement_updates_canvas() {
+    let (state, _) = common::test_state();
+    place!(state, "user-1", 5, 5, 0xAA).unwrap();
+
+    let pixels = application::canvas::get_state::execute(&state);
+    let idx = 5 * 10 + 5;
+    assert_eq!(pixels[idx], Color::new(0xAA));
+}
+
+#[test]
+fn placement_publishes_broadcast_event() {
+    let (state, spy) = common::test_state();
+    place!(state, "user-1", 0, 0, 0xFF).unwrap();
+
+    let events = spy.events();
+    assert_eq!(events.len(), 1);
+    assert!(matches!(events[0], BroadcastEvent::PixelUpdated(_)));
+}
+
+#[test]
+fn cooldown_blocks_rapid_placement() {
+    let (state, _) = common::test_state();
+    place!(state, "user-1", 0, 0, 0xFF).unwrap();
+
+    let result = place!(state, "user-1", 1, 1, 0xAA).unwrap();
+    assert!(matches!(result, Outcome::CooldownActive));
+}
+
+#[test]
+fn cooldown_is_per_user() {
+    let (state, _) = common::test_state();
+    place!(state, "user-1", 0, 0, 0xFF).unwrap();
+
+    let result = place!(state, "user-2", 1, 1, 0xAA).unwrap();
+    assert!(matches!(result, Outcome::Placed(_)));
+}
+
+#[test]
+fn zero_cooldown_allows_rapid_placement() {
+    let (state, _) = common::test_state_no_cooldown();
+    place!(state, "user-1", 0, 0, 0xFF).unwrap();
+
+    let result = place!(state, "user-1", 1, 1, 0xAA).unwrap();
+    assert!(matches!(result, Outcome::Placed(_)));
+}
+
+#[test]
+fn out_of_bounds_returns_error() {
+    let (state, _) = common::test_state();
+    assert!(place!(state, "user-1", 99, 99, 0xFF).is_err());
+}
+
+#[test]
+fn failed_placement_does_not_trigger_cooldown() {
+    let (state, _) = common::test_state();
+    let _ = place!(state, "user-1", 99, 99, 0xFF);
+
+    let result = place!(state, "user-1", 0, 0, 0xFF).unwrap();
+    assert!(matches!(result, Outcome::Placed(_)));
+}

crates/application/tests/snapshots.rs

@@ -0,0 +1,75 @@
+mod common;
+
+use std::sync::Arc;
+
+use application::AppState;
+use domain::Color;
+
+fn state_with_persistence(persistence: common::FakePersistence) -> Arc<AppState> {
+    let spy = common::SpyBroadcaster::new();
+    let state = AppState::new(
+        Box::new(application::InMemoryCanvasStore::new(10, 10)),
+        Box::new(spy),
+        std::time::Duration::from_secs(10),
+    )
+    .with_persistence(Box::new(persistence));
+    Arc::new(state)
+}
+
+#[test]
+fn save_snapshot_persists_current_canvas() {
+    let persistence = common::FakePersistence::empty();
+    let saved_ref = persistence.saved_ref();
+    let state = state_with_persistence(persistence);
+
+    application::canvas::place_pixel::execute(
+        &state,
+        application::canvas::place_pixel::Command {
+            user_id: "user",
+            position: domain::Position::new(0, 0),
+            color: Color::new(0xFF),
+        },
+    )
+    .unwrap();
+
+    application::canvas::save_snapshot::execute(&state).unwrap();
+
+    let snapshots = saved_ref.lock().unwrap();
+    assert_eq!(snapshots.len(), 1);
+    assert_eq!(snapshots[0][0], Color::new(0xFF));
+    assert_eq!(snapshots[0].len(), 100);
+}
+
+#[test]
+fn restore_snapshot_loads_canvas() {
+    let mut snapshot = vec![Color::white(); 100];
+    snapshot[0] = Color::new(0xDEAD);
+    snapshot[99] = Color::new(0xBEEF);
+
+    let state = state_with_persistence(common::FakePersistence::with_snapshot(snapshot));
+
+    let restored = application::canvas::restore_snapshot::execute(&state).unwrap();
+    assert!(restored);
+
+    let pixels = application::canvas::get_state::execute(&state);
+    assert_eq!(pixels[0], Color::new(0xDEAD));
+    assert_eq!(pixels[99], Color::new(0xBEEF));
+}
+
+#[test]
+fn restore_returns_false_when_no_snapshot() {
+    let state = state_with_persistence(common::FakePersistence::empty());
+    assert!(!application::canvas::restore_snapshot::execute(&state).unwrap());
+}
+
+#[test]
+fn save_without_persistence_is_noop() {
+    let (state, _) = common::test_state();
+    assert!(application::canvas::save_snapshot::execute(&state).is_ok());
+}
+
+#[test]
+fn restore_without_persistence_returns_false() {
+    let (state, _) = common::test_state();
+    assert!(!application::canvas::restore_snapshot::execute(&state).unwrap());
+}

crates/application/tests/soldiers.rs

@@ -0,0 +1,96 @@
+mod common;
+
+use domain::BroadcastEvent;
+
+#[test]
+fn connect_increments_count() {
+    let (state, _) = common::test_state();
+    assert_eq!(
+        application::soldiers::connect::execute(&state, "a".into()),
+        1
+    );
+    assert_eq!(
+        application::soldiers::connect::execute(&state, "b".into()),
+        2
+    );
+    assert_eq!(
+        application::soldiers::connect::execute(&state, "c".into()),
+        3
+    );
+}
+
+#[test]
+fn disconnect_decrements_count() {
+    let (state, _) = common::test_state();
+    application::soldiers::connect::execute(&state, "a".into());
+    application::soldiers::connect::execute(&state, "b".into());
+
+    assert_eq!(application::soldiers::disconnect::execute(&state, "a"), 1);
+    assert_eq!(application::soldiers::disconnect::execute(&state, "b"), 0);
+}
+
+#[test]
+fn disconnect_unknown_user_is_harmless() {
+    let (state, _) = common::test_state();
+    application::soldiers::connect::execute(&state, "a".into());
+    assert_eq!(
+        application::soldiers::disconnect::execute(&state, "unknown"),
+        1
+    );
+}
+
+#[test]
+fn connect_publishes_soldier_count() {
+    let (state, spy) = common::test_state();
+    application::soldiers::connect::execute(&state, "a".into());
+
+    let events = spy.events();
+    assert_eq!(events.len(), 1);
+    assert!(matches!(events[0], BroadcastEvent::SoldierCountChanged(1)));
+}
+
+#[test]
+fn disconnect_publishes_soldier_count() {
+    let (state, spy) = common::test_state();
+    application::soldiers::connect::execute(&state, "a".into());
+    application::soldiers::disconnect::execute(&state, "a");
+
+    let events = spy.events();
+    assert_eq!(events.len(), 2);
+    assert!(matches!(events[1], BroadcastEvent::SoldierCountChanged(0)));
+}
+
+#[test]
+fn disconnect_clears_cooldown() {
+    let (state, _) = common::test_state();
+    application::soldiers::connect::execute(&state, "user-1".into());
+
+    application::canvas::place_pixel::execute(
+        &state,
+        application::canvas::place_pixel::Command {
+            user_id: "user-1",
+            position: domain::Position::new(0, 0),
+            color: domain::Color::new(0xFF),
+        },
+    )
+    .unwrap();
+
+    application::soldiers::disconnect::execute(&state, "user-1");
+
+    // Reconnect with same ID — cooldown should be gone
+    application::soldiers::connect::execute(&state, "user-1".into());
+    let result = application::canvas::place_pixel::execute(
+        &state,
+        application::canvas::place_pixel::Command {
+            user_id: "user-1",
+            position: domain::Position::new(1, 1),
+            color: domain::Color::new(0xAA),
+        },
+    )
+    .unwrap();
+
+    assert!(matches!(
+        result,
+        application::canvas::place_pixel::Outcome::Placed(_)
+    ));
+}