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/src/canvas/get_state.rs

@@ -0,0 +1,9 @@
+use std::sync::Arc;
+
+use domain::Color;
+
+use crate::AppState;
+
+pub fn execute(state: &AppState) -> Arc<[Color]> {
+    state.canvas().pixels()
+}

crates/application/src/canvas/mod.rs

@@ -0,0 +1,4 @@
+pub mod get_state;
+pub mod place_pixel;
+pub mod restore_snapshot;
+pub mod save_snapshot;

crates/application/src/canvas/place_pixel.rs

@@ -0,0 +1,29 @@
+use domain::{BroadcastEvent, Color, PixelUpdate, Position};
+
+use crate::{AppState, ApplicationError};
+
+pub struct Command<'a> {
+    pub user_id: &'a str,
+    pub position: Position,
+    pub color: Color,
+}
+
+pub enum Outcome {
+    Placed(PixelUpdate),
+    CooldownActive,
+}
+
+pub fn execute(state: &AppState, command: Command<'_>) -> Result<Outcome, ApplicationError> {
+    if state.cooldowns().is_on_cooldown(command.user_id) {
+        return Ok(Outcome::CooldownActive);
+    }
+    state
+        .canvas()
+        .place_pixel(command.position, command.color)?;
+    state.cooldowns().record(command.user_id);
+    let update = PixelUpdate::new(command.position, command.color);
+    state
+        .broadcaster()
+        .publish(BroadcastEvent::PixelUpdated(update));
+    Ok(Outcome::Placed(update))
+}

crates/application/src/canvas/restore_snapshot.rs

@@ -0,0 +1,14 @@
+use crate::{AppState, ApplicationError};
+
+pub fn execute(state: &AppState) -> Result<bool, ApplicationError> {
+    let Some(persistence) = state.persistence() else {
+        return Ok(false);
+    };
+    match persistence.load_latest()? {
+        Some(pixels) => {
+            state.canvas().restore(pixels)?;
+            Ok(true)
+        }
+        None => Ok(false),
+    }
+}

crates/application/src/canvas/save_snapshot.rs

@@ -0,0 +1,10 @@
+use crate::{AppState, ApplicationError};
+
+pub fn execute(state: &AppState) -> Result<(), ApplicationError> {
+    let Some(persistence) = state.persistence() else {
+        return Ok(());
+    };
+    let pixels = state.canvas().pixels();
+    persistence.save(&pixels)?;
+    Ok(())
+}

crates/application/src/errors.rs

@@ -0,0 +1,7 @@
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum ApplicationError {
+    #[error(transparent)]
+    Domain(#[from] domain::DomainError),
+}

crates/application/src/lib.rs

@@ -0,0 +1,8 @@
+mod errors;
+mod state;
+
+pub mod canvas;
+pub mod soldiers;
+
+pub use errors::ApplicationError;
+pub use state::{AppState, InMemoryCanvasStore, InProcessBroadcaster};

crates/application/src/soldiers/connect.rs

@@ -0,0 +1,11 @@
+use domain::BroadcastEvent;
+
+use crate::AppState;
+
+pub fn execute(state: &AppState, user_id: String) -> usize {
+    let count = state.soldiers().add(user_id);
+    state
+        .broadcaster()
+        .publish(BroadcastEvent::SoldierCountChanged(count));
+    count
+}

crates/application/src/soldiers/disconnect.rs

@@ -0,0 +1,12 @@
+use domain::BroadcastEvent;
+
+use crate::AppState;
+
+pub fn execute(state: &AppState, user_id: &str) -> usize {
+    state.cooldowns().remove(user_id);
+    let count = state.soldiers().remove(user_id);
+    state
+        .broadcaster()
+        .publish(BroadcastEvent::SoldierCountChanged(count));
+    count
+}

crates/application/src/soldiers/mod.rs

@@ -0,0 +1,2 @@
+pub mod connect;
+pub mod disconnect;

crates/application/src/state.rs

@@ -0,0 +1,199 @@
+use std::collections::{HashMap, HashSet};
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex, MutexGuard};
+use std::time::{Duration, Instant};
+
+use domain::ports::{
+    BroadcastReceiverInner, BroadcastSubscription, CanvasPersistence, CanvasStore, EventBroadcaster,
+};
+use domain::{BroadcastEvent, Canvas, Color, DomainError, Position};
+use tokio::sync::broadcast;
+use tracing::warn;
+
+const INITIAL_CONNECTION_CAPACITY: usize = 128;
+
+pub struct AppState {
+    canvas: Box<dyn CanvasStore>,
+    broadcaster: Box<dyn EventBroadcaster>,
+    persistence: Option<Box<dyn CanvasPersistence>>,
+    cooldowns: CooldownTracker,
+    soldiers: SoldierTracker,
+}
+
+impl AppState {
+    pub fn new(
+        canvas: Box<dyn CanvasStore>,
+        broadcaster: Box<dyn EventBroadcaster>,
+        cooldown: Duration,
+    ) -> Self {
+        Self {
+            canvas,
+            broadcaster,
+            persistence: None,
+            cooldowns: CooldownTracker::new(cooldown),
+            soldiers: SoldierTracker::new(),
+        }
+    }
+
+    pub fn with_persistence(mut self, persistence: Box<dyn CanvasPersistence>) -> Self {
+        self.persistence = Some(persistence);
+        self
+    }
+
+    pub fn canvas(&self) -> &dyn CanvasStore {
+        &*self.canvas
+    }
+
+    pub fn broadcaster(&self) -> &dyn EventBroadcaster {
+        &*self.broadcaster
+    }
+
+    pub fn persistence(&self) -> Option<&dyn CanvasPersistence> {
+        self.persistence.as_deref()
+    }
+
+    pub fn cooldowns(&self) -> &CooldownTracker {
+        &self.cooldowns
+    }
+
+    pub fn soldiers(&self) -> &SoldierTracker {
+        &self.soldiers
+    }
+}
+
+pub struct InProcessBroadcaster {
+    sender: broadcast::Sender<BroadcastEvent>,
+}
+
+impl InProcessBroadcaster {
+    pub fn new(sender: broadcast::Sender<BroadcastEvent>) -> Self {
+        Self { sender }
+    }
+}
+
+impl EventBroadcaster for InProcessBroadcaster {
+    fn publish(&self, event: BroadcastEvent) {
+        let _ = self.sender.send(event);
+    }
+
+    fn subscribe(&self) -> BroadcastSubscription {
+        BroadcastSubscription::new(Box::new(TokioBroadcastReceiver(self.sender.subscribe())))
+    }
+}
+
+struct TokioBroadcastReceiver(broadcast::Receiver<BroadcastEvent>);
+
+impl BroadcastReceiverInner for TokioBroadcastReceiver {
+    fn recv_boxed(&mut self) -> Pin<Box<dyn Future<Output = Option<BroadcastEvent>> + Send + '_>> {
+        Box::pin(async { self.0.recv().await.ok() })
+    }
+}
+
+fn acquire_lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
+    mutex.lock().unwrap_or_else(|poisoned| {
+        warn!("Recovered from poisoned mutex");
+        poisoned.into_inner()
+    })
+}
+
+struct CanvasState {
+    canvas: Canvas,
+    snapshot: Option<Arc<[Color]>>,
+}
+
+pub struct InMemoryCanvasStore {
+    state: Mutex<CanvasState>,
+}
+
+impl InMemoryCanvasStore {
+    pub fn new(width: u32, height: u32) -> Self {
+        Self {
+            state: Mutex::new(CanvasState {
+                canvas: Canvas::new(width, height),
+                snapshot: None,
+            }),
+        }
+    }
+}
+
+impl CanvasStore for InMemoryCanvasStore {
+    fn pixels(&self) -> Arc<[Color]> {
+        let mut state = acquire_lock(&self.state);
+        if let Some(ref cached) = state.snapshot {
+            return cached.clone();
+        }
+        let new_snapshot: Arc<[Color]> = Arc::from(state.canvas.pixels());
+        state.snapshot = Some(new_snapshot.clone());
+        new_snapshot
+    }
+
+    fn place_pixel(&self, position: Position, color: Color) -> Result<(), DomainError> {
+        let mut state = acquire_lock(&self.state);
+        state.canvas.place_pixel(position, color)?;
+        state.snapshot = None;
+        Ok(())
+    }
+
+    fn restore(&self, pixels: Vec<Color>) -> Result<(), DomainError> {
+        let mut state = acquire_lock(&self.state);
+        let new_canvas = Canvas::from_pixels(state.canvas.width(), state.canvas.height(), pixels)?;
+        state.canvas = new_canvas;
+        state.snapshot = None;
+        Ok(())
+    }
+}
+
+pub struct CooldownTracker {
+    entries: Mutex<HashMap<String, Instant>>,
+    cooldown: Duration,
+}
+
+impl CooldownTracker {
+    pub fn new(cooldown: Duration) -> Self {
+        Self {
+            entries: Mutex::new(HashMap::with_capacity(INITIAL_CONNECTION_CAPACITY)),
+            cooldown,
+        }
+    }
+
+    pub fn is_on_cooldown(&self, user_id: &str) -> bool {
+        let entries = acquire_lock(&self.entries);
+        entries
+            .get(user_id)
+            .map(|last| last.elapsed() < self.cooldown)
+            .unwrap_or(false)
+    }
+
+    pub fn record(&self, user_id: &str) {
+        acquire_lock(&self.entries).insert(user_id.to_string(), Instant::now());
+    }
+
+    pub fn remove(&self, user_id: &str) {
+        acquire_lock(&self.entries).remove(user_id);
+    }
+}
+
+pub struct SoldierTracker {
+    connected: Mutex<HashSet<String>>,
+}
+
+impl SoldierTracker {
+    pub fn new() -> Self {
+        Self {
+            connected: Mutex::new(HashSet::with_capacity(INITIAL_CONNECTION_CAPACITY)),
+        }
+    }
+
+    pub fn add(&self, user_id: String) -> usize {
+        let mut connected = acquire_lock(&self.connected);
+        connected.insert(user_id);
+        connected.len()
+    }
+
+    pub fn remove(&self, user_id: &str) -> usize {
+        let mut connected = acquire_lock(&self.connected);
+        connected.remove(user_id);
+        connected.len()
+    }
+}