refactor: reorganize project into monorepo with frontend scaffolding

Convert project from single backend to monorepo structure with separate
frontend (Vue 3 + TypeScript + Vite) and backend directories. Updates
all configuration files and build system to support both workspaces.

Ref: T007 (specs/001-modbus-relay-control)

backend/src/application/mod.rs

@@ -0,0 +1,60 @@
+//! Application layer - Use cases and orchestration logic
+//!
+//! This module implements business use cases by coordinating domain entities and
+//! infrastructure services. It contains the application logic that orchestrates
+//! domain behavior without implementing domain rules directly.
+//!
+//! # Architecture Principles
+//!
+//! - **Depends on Domain layer**: Uses domain entities, value objects, and traits
+//! - **Framework-independent**: No dependencies on HTTP, database, or other infrastructure
+//! - **Use case driven**: Each module represents a specific business use case
+//! - **Testable in isolation**: Can be tested with mock infrastructure implementations
+//!
+//! # Planned Submodules
+//!
+//! - `relay`: Relay control use cases
+//!   - `get_status`: Retrieve current state of one or all relays
+//!   - `toggle_relay`: Switch relay on/off with validation
+//!   - `bulk_control`: Control multiple relays (all on, all off, pattern)
+//!   - `update_label`: Manage relay labels with persistence
+//!   - `get_health`: Check device health and connectivity
+//!
+//! # Use Case Pattern
+//!
+//! Each use case follows this pattern:
+//! 1. Accept domain types as input (validated at boundary)
+//! 2. Orchestrate domain entities and services
+//! 3. Return domain types or application-specific results
+//! 4. Depend on traits (RelayController, RelayLabelRepository), not concrete types
+//!
+//! # Example Use Case Structure
+//!
+//! ```rust,ignore
+//! pub struct ToggleRelay {
+//!     controller: Arc<dyn RelayController>,
+//!     repository: Arc<dyn RelayLabelRepository>,
+//! }
+//!
+//! impl ToggleRelay {
+//!     pub async fn execute(&self, relay_id: RelayId) -> Result<Relay, ApplicationError> {
+//!         // 1. Read current state
+//!         let current = self.controller.read_relay_state(relay_id).await?;
+//!
+//!         // 2. Toggle state (domain logic)
+//!         let new_state = current.toggle();
+//!
+//!         // 3. Write new state
+//!         self.controller.write_relay_state(relay_id, new_state).await?;
+//!
+//!         // 4. Return updated relay
+//!         Ok(Relay::new(relay_id, new_state))
+//!     }
+//! }
+//! ```
+//!
+//! # References
+//!
+//! - Architecture: `specs/constitution.md` - Hexagonal Architecture principles
+//! - Use cases: `specs/001-modbus-relay-control/plan.md` - Implementation plan
+//! - Domain types: [`crate::domain`] - Domain entities and value objects

backend/src/domain/mod.rs

@@ -0,0 +1,38 @@
+//! Domain layer - Pure business logic with no external dependencies
+//!
+//! This module contains the core business domain for the StA relay control system.
+//! It follows **Domain-Driven Design** principles with rich domain models and clear
+//! ubiquitous language.
+//!
+//! # Architecture Principles
+//!
+//! - **No external dependencies**: Domain layer depends only on Rust standard library
+//! - **Inward-pointing dependencies**: Infrastructure/Application depend on Domain, never reverse
+//! - **Rich domain models**: Entities and value objects encapsulate business rules
+//! - **Ubiquitous language**: Code reflects real-world relay control domain concepts
+//!
+//! # Planned Submodules
+//!
+//! - `relay`: Core relay domain (RelayId, RelayState, RelayLabel, Relay entity)
+//!   - Value objects with validation (newtypes following TyDD principles)
+//!   - Domain entities (Relay, RelayCollection)
+//!   - Repository traits (RelayLabelRepository)
+//!   - Controller traits (RelayController)
+//!   - Domain errors (DomainError, ValidationError)
+//!
+//! # Type-Driven Development (TyDD)
+//!
+//! Domain types follow "make illegal states unrepresentable" principle:
+//! - `RelayId`: Newtype wrapping u8, validated to 1..=8 range
+//! - `RelayLabel`: String wrapper, validated max 50 chars
+//! - `RelayState`: Enum (On, Off) - no invalid states possible
+//!
+//! See `specs/001-modbus-relay-control/types-design.md` for complete type design.
+//!
+//! # References
+//!
+//! - Architecture: `specs/constitution.md` - Hexagonal Architecture principles
+//! - Type design: `specs/001-modbus-relay-control/types-design.md`
+//! - Domain specification: `specs/001-modbus-relay-control/spec.md`
+
+pub mod relay;

backend/src/domain/relay/mod.rs

@@ -0,0 +1,9 @@
+//! Relay domain module.
+//!
+//! This module contains the core domain logic for relay control and management,
+//! including relay types, repository abstractions, and business rules.
+
+/// Repository trait and error types for relay persistence.
+pub mod repository;
+/// Domain types for relay identification and control.
+pub mod types;

backend/src/domain/relay/repository.rs

@@ -0,0 +1,15 @@
+use super::types::RelayId;
+
+/// Errors that can occur during repository operations.
+///
+/// This enum provides structured error handling for all data persistence
+/// operations related to relay management.
+#[derive(Debug, thiserror::Error)]
+pub enum RepositoryError {
+    /// A database operation failed with the given error message.
+    #[error("Database error: {0}")]
+    DatabaseError(String),
+    /// The requested relay was not found in the repository.
+    #[error("Relay not found: {0}")]
+    NotFound(RelayId),
+}

backend/src/domain/relay/types.rs

@@ -0,0 +1,14 @@
+/// Unique identifier for a relay in the system.
+///
+/// Uses the newtype pattern to provide type safety and prevent mixing relay IDs
+/// with other numeric values. Valid values range from 0-255, corresponding to
+/// individual relay channels in the Modbus controller.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[repr(transparent)]
+pub struct RelayId(u8);
+
+impl std::fmt::Display for RelayId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}

backend/src/infrastructure/mod.rs

@@ -0,0 +1,78 @@
+//! Infrastructure layer - External integrations and adapters
+//!
+//! This module implements the technical infrastructure required by the application,
+//! including external system integrations, persistence, and communication protocols.
+//! All infrastructure depends on domain/application layers through trait implementations.
+//!
+//! # Architecture Principles
+//!
+//! - **Implements domain traits**: Provides concrete implementations of domain interfaces
+//! - **Depends inward**: Depends on domain/application, never the reverse
+//! - **Substitutable**: Different implementations can be swapped without changing domain
+//! - **Framework-specific**: Contains framework and library dependencies (Modbus, SQLx, etc.)
+//!
+//! # Planned Submodules
+//!
+//! ## `modbus` - Modbus RTU over TCP Integration
+//!
+//! - `client`: ModbusRelayController implementation using tokio-modbus
+//! - `mock`: MockRelayController for testing without hardware
+//! - `config`: Modbus connection configuration
+//! - `connection`: Connection pool and health management
+//!
+//! Implements: [`domain::relay::controller::RelayController`](crate::domain)
+//!
+//! ## `persistence` - SQLite Database with SQLx
+//!
+//! - `sqlite_repository`: SqliteRelayLabelRepository implementation
+//! - `schema.sql`: Database schema with relay_labels table
+//! - `migrations`: Database migration scripts (if using sqlx-cli)
+//!
+//! Implements: [`domain::relay::repository::RelayLabelRepository`](crate::domain)
+//!
+//! # Technology Stack
+//!
+//! - **Modbus**: `tokio-modbus` 0.17.0 for async Modbus RTU over TCP
+//! - **Persistence**: `sqlx` 0.8 for compile-time verified SQLite queries
+//! - **Async Runtime**: `tokio` 1.48 (shared with main application)
+//! - **Testing**: `mockall` 0.13 for mock implementations
+//!
+//! # Implementation Pattern
+//!
+//! Each infrastructure adapter:
+//! 1. Implements domain-defined trait (e.g., `RelayController`)
+//! 2. Translates domain types to/from external formats
+//! 3. Handles connection management and retries
+//! 4. Provides error translation (external errors → domain errors)
+//!
+//! # Example: Modbus Controller
+//!
+//! ```rust,ignore
+//! pub struct ModbusRelayController {
+//!     client: Arc<Mutex<ModbusClient>>,
+//!     config: ModbusConfig,
+//! }
+//!
+//! #[async_trait]
+//! impl RelayController for ModbusRelayController {
+//!     async fn read_relay_state(&self, id: RelayId) -> Result<RelayState, ControllerError> {
+//!         let address = self.config.base_address + id.value() as u16;
+//!         let mut client = self.client.lock().await;
+//!
+//!         // Read coil from Modbus device
+//!         let result = client.read_coils(address, 1).await
+//!             .map_err(|e| ControllerError::CommunicationError(e.to_string()))?;
+//!
+//!         // Translate to domain type
+//!         Ok(if result[0] { RelayState::On } else { RelayState::Off })
+//!     }
+//! }
+//! ```
+//!
+//! # References
+//!
+//! - Architecture: `specs/constitution.md` - Dependency Inversion Principle
+//! - Implementation: `specs/001-modbus-relay-control/plan.md` - Infrastructure tasks
+//! - Modbus docs: `docs/Modbus_POE_ETH_Relay.md` - Hardware protocol specification
+
+pub mod persistence;

backend/src/infrastructure/persistence/mod.rs

@@ -0,0 +1,7 @@
+//! Persistence layer implementations.
+//!
+//! This module contains the concrete implementations of repository traits
+//! for data persistence, including SQLite-based storage for relay labels.
+
+/// `SQLite` repository implementation for relay labels.
+pub mod sqlite_repository;

backend/src/infrastructure/persistence/sqlite_repository.rs

@@ -0,0 +1,64 @@
+use sqlx::SqlitePool;
+
+use crate::domain::relay::repository::RepositoryError;
+
+/// `SQLite` implementation of the relay label repository.
+///
+/// This repository manages persistent storage of relay labels using `SQLite`,
+/// with automatic schema migrations via `SQLx`.
+pub struct SqliteRelayLabelRepository {
+    /// The `SQLite` connection pool for database operations.
+    pool: SqlitePool,
+}
+
+impl SqliteRelayLabelRepository {
+    /// Creates a new `SQLite` relay label repository.
+    ///
+    /// # Arguments
+    ///
+    /// * `db_path` - The `SQLite` database path or connection string (e.g., `"sqlite://data.db"`)
+    ///
+    /// # Errors
+    ///
+    /// Returns `RepositoryError::DatabaseError` if the connection fails or migrations cannot be applied.
+    pub async fn new(db_path: &str) -> Result<Self, RepositoryError> {
+        let pool = SqlitePool::connect(db_path)
+            .await
+            .map_err(|e| RepositoryError::DatabaseError(e.to_string()))?;
+        let repo = Self { pool };
+        repo.run_migrations().await?;
+        Ok(repo)
+    }
+
+    /// Returns a reference to the underlying connection pool.
+    ///
+    /// This is primarily used for testing to verify schema and constraints.
+    #[must_use]
+    pub const fn pool(&self) -> &SqlitePool {
+        &self.pool
+    }
+
+    /// Creates a new in-memory `SQLite` relay label repository.
+    ///
+    /// This is useful for testing and ephemeral data storage.
+    ///
+    /// # Errors
+    ///
+    /// Returns `RepositoryError::DatabaseError` if the in-memory database cannot be created.
+    pub async fn in_memory() -> Result<Self, RepositoryError> {
+        Self::new("sqlite::memory:").await
+    }
+
+    /// Runs all pending database migrations.
+    ///
+    /// # Errors
+    ///
+    /// Returns `RepositoryError::DatabaseError` if migrations fail to apply.
+    async fn run_migrations(&self) -> Result<(), RepositoryError> {
+        sqlx::migrate!("../migrations/")
+            .run(&self.pool)
+            .await
+            .map_err(|e| RepositoryError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+}

backend/src/lib.rs

@@ -0,0 +1,143 @@
+//! Backend API server for `StA` (Smart Temperature & Appliance Control)
+//!
+//! `StA` is a web-based Modbus relay control system that provides `RESTful` API access
+//! to 8-channel relay devices. The system eliminates the need for specialized Modbus
+//! software, enabling browser-based relay control for automation and remote management.
+//!
+//! # Architecture
+//!
+//! This crate follows **Hexagonal Architecture** (Clean Architecture) with strict
+//! layer separation and inward-pointing dependencies:
+//!
+//! - **[`domain`]**: Pure business logic with no external dependencies (relay entities, value objects)
+//! - **[`application`]**: Use cases and orchestration logic (relay control, label management)
+//! - **[`infrastructure`]**: External integrations (Modbus TCP, `SQLite` persistence)
+//! - **[`presentation`]**: API contracts and DTOs (not yet used - see [`route`] for current API)
+//!
+//! Traditional modules (will be migrated to hexagonal layers):
+//! - **[`route`]**: HTTP API endpoints (will move to `presentation`)
+//! - **[`middleware`]**: Custom middleware (rate limiting, CORS)
+//! - **[`settings`]**: Configuration management from YAML + env vars
+//! - **[`startup`]**: Application builder and server configuration
+//! - **[`telemetry`]**: Logging and tracing setup
+//!
+//! # Current Features
+//!
+//! - Health check endpoints
+//! - Application metadata endpoints
+//! - Rate limiting middleware
+//! - CORS support
+//! - `OpenAPI` documentation
+//!
+//! # Planned Features (001-modbus-relay-control)
+//!
+//! - Modbus RTU over TCP communication with 8-channel relay devices
+//! - Real-time relay status monitoring
+//! - Individual relay control (on/off toggle)
+//! - Bulk relay operations (all on, all off)
+//! - Persistent relay labels (`SQLite` with `SQLx`)
+//! - Device health monitoring
+//!
+//! See `specs/001-modbus-relay-control/` for detailed specification.
+
+#![deny(clippy::all)]
+#![deny(clippy::pedantic)]
+#![deny(clippy::nursery)]
+#![warn(missing_docs)]
+#![allow(clippy::unused_async)]
+
+/// Custom middleware implementations
+pub mod middleware;
+/// API route handlers and endpoints
+pub mod route;
+/// Application configuration settings
+pub mod settings;
+/// Application startup and server configuration
+pub mod startup;
+/// Logging and tracing setup
+pub mod telemetry;
+
+/// Domain layer - Pure business logic with no external dependencies
+///
+/// Contains domain entities, value objects, and business rules for the relay
+/// control system. This layer has no dependencies on frameworks or infrastructure.
+///
+/// See `specs/constitution.md` for hexagonal architecture principles.
+pub mod domain;
+
+/// Application layer - Use cases and orchestration logic
+///
+/// Coordinates domain entities to implement business use cases such as relay
+/// control, label management, and device health monitoring.
+pub mod application;
+
+/// Infrastructure layer - External integrations and adapters
+///
+/// Implements interfaces defined in domain/application layers for external
+/// systems: Modbus TCP communication, SQLite persistence, HTTP clients.
+pub mod infrastructure;
+
+/// Presentation layer - API contracts and DTOs
+///
+/// Defines data transfer objects and API request/response types. Currently
+/// unused - API handlers are in [`route`] module (legacy structure).
+pub mod presentation;
+
+type MaybeListener = Option<poem::listener::TcpListener<String>>;
+
+fn prepare(listener: MaybeListener) -> startup::Application {
+    dotenvy::dotenv().ok();
+    let settings = settings::Settings::new().expect("Failed to read settings");
+    if !cfg!(test) {
+        let subscriber = telemetry::get_subscriber(settings.debug);
+        telemetry::init_subscriber(subscriber);
+    }
+    tracing::event!(
+        target: "backend",
+        tracing::Level::DEBUG,
+        "Using these settings: {:?}",
+        settings
+    );
+    let application = startup::Application::build(settings, listener);
+    tracing::event!(
+        target: "backend",
+        tracing::Level::INFO,
+        "Listening on http://{}:{}/",
+        application.host(),
+        application.port()
+    );
+    tracing::event!(
+        target: "backend",
+        tracing::Level::INFO,
+        "Documentation available at http://{}:{}/",
+        application.host(),
+        application.port()
+    );
+    application
+}
+
+/// Runs the application with the specified TCP listener.
+///
+/// # Errors
+///
+/// Returns a `std::io::Error` if the server fails to start or encounters
+/// an I/O error during runtime (e.g., port already in use, network issues).
+#[cfg(not(tarpaulin_include))]
+pub async fn run(listener: MaybeListener) -> Result<(), std::io::Error> {
+    let application = prepare(listener);
+    application.make_app().run().await
+}
+
+#[cfg(test)]
+fn make_random_tcp_listener() -> poem::listener::TcpListener<String> {
+    let tcp_listener =
+        std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind a random TCP listener");
+    let port = tcp_listener.local_addr().unwrap().port();
+    poem::listener::TcpListener::bind(format!("127.0.0.1:{port}"))
+}
+
+#[cfg(test)]
+fn get_test_app() -> startup::App {
+    let tcp_listener = make_random_tcp_listener();
+    prepare(Some(tcp_listener)).make_app().into()
+}

backend/src/main.rs

@@ -0,0 +1,7 @@
+//! Backend server entry point.
+
+#[cfg(not(tarpaulin_include))]
+#[tokio::main]
+async fn main() -> Result<(), std::io::Error> {
+    sta::run(None).await
+}

backend/src/middleware/mod.rs

@@ -0,0 +1,5 @@
+//! Custom middleware for the application.
+//!
+//! This module contains custom middleware implementations including rate limiting.
+
+pub mod rate_limit;

backend/src/middleware/rate_limit.rs

@@ -0,0 +1,208 @@
+//! Rate limiting middleware using the governor crate.
+//!
+//! This middleware implements per-IP rate limiting using the Generic Cell Rate
+//! Algorithm (GCRA) via the governor crate. It stores rate limiters in memory
+//! without requiring external dependencies like Redis.
+
+use std::{net::IpAddr, num::NonZeroU32, sync::Arc, time::Duration};
+
+use governor::{
+    Quota, RateLimiter,
+    clock::DefaultClock,
+    state::{InMemoryState, NotKeyed},
+};
+use poem::{Endpoint, Error, IntoResponse, Middleware, Request, Response, Result};
+
+/// Rate limiting configuration.
+#[derive(Debug, Clone)]
+pub struct RateLimitConfig {
+    /// Maximum number of requests allowed in the time window (burst size).
+    pub burst_size: u32,
+    /// Time window in seconds for rate limiting.
+    pub per_seconds: u64,
+}
+
+impl RateLimitConfig {
+    /// Creates a new rate limit configuration.
+    ///
+    /// # Arguments
+    ///
+    /// * `burst_size` - Maximum number of requests allowed in the time window
+    /// * `per_seconds` - Time window in seconds
+    #[must_use]
+    pub const fn new(burst_size: u32, per_seconds: u64) -> Self {
+        Self {
+            burst_size,
+            per_seconds,
+        }
+    }
+
+    /// Creates a rate limiter from this configuration.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `burst_size` is zero.
+    #[must_use]
+    pub fn create_limiter(&self) -> RateLimiter<NotKeyed, InMemoryState, DefaultClock> {
+        let quota = Quota::with_period(Duration::from_secs(self.per_seconds))
+            .expect("Failed to create quota")
+            .allow_burst(NonZeroU32::new(self.burst_size).expect("Burst size must be non-zero"));
+        RateLimiter::direct(quota)
+    }
+}
+
+impl Default for RateLimitConfig {
+    fn default() -> Self {
+        // Default: 10 requests per second with burst of 20
+        Self::new(20, 1)
+    }
+}
+
+/// Middleware for rate limiting based on IP address.
+pub struct RateLimit {
+    limiter: Arc<RateLimiter<NotKeyed, InMemoryState, DefaultClock>>,
+}
+
+impl RateLimit {
+    /// Creates a new rate limiting middleware with the given configuration.
+    #[must_use]
+    pub fn new(config: &RateLimitConfig) -> Self {
+        Self {
+            limiter: Arc::new(config.create_limiter()),
+        }
+    }
+}
+
+impl<E: Endpoint> Middleware<E> for RateLimit {
+    type Output = RateLimitEndpoint<E>;
+
+    fn transform(&self, ep: E) -> Self::Output {
+        RateLimitEndpoint {
+            endpoint: ep,
+            limiter: self.limiter.clone(),
+        }
+    }
+}
+
+/// The endpoint wrapper that performs rate limiting checks.
+pub struct RateLimitEndpoint<E> {
+    endpoint: E,
+    limiter: Arc<RateLimiter<NotKeyed, InMemoryState, DefaultClock>>,
+}
+
+impl<E: Endpoint> Endpoint for RateLimitEndpoint<E> {
+    type Output = Response;
+
+    async fn call(&self, req: Request) -> Result<Self::Output> {
+        // Check rate limit
+        if self.limiter.check().is_err() {
+            let client_ip = Self::get_client_ip(&req)
+                .map_or_else(|| "unknown".to_string(), |ip| ip.to_string());
+
+            tracing::event!(
+                target: "backend::middleware::rate_limit",
+                tracing::Level::WARN,
+                client_ip = %client_ip,
+                "Rate limit exceeded"
+            );
+
+            return Err(Error::from_status(
+                poem::http::StatusCode::TOO_MANY_REQUESTS,
+            ));
+        }
+
+        // Process the request
+        let response = self.endpoint.call(req).await;
+        response.map(IntoResponse::into_response)
+    }
+}
+
+impl<E> RateLimitEndpoint<E> {
+    /// Extracts the client IP address from the request.
+    fn get_client_ip(req: &Request) -> Option<IpAddr> {
+        req.remote_addr()
+            .as_socket_addr()
+            .map(std::net::SocketAddr::ip)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rate_limit_config_new() {
+        let config = RateLimitConfig::new(10, 60);
+        assert_eq!(config.burst_size, 10);
+        assert_eq!(config.per_seconds, 60);
+    }
+
+    #[test]
+    fn rate_limit_config_default() {
+        let config = RateLimitConfig::default();
+        assert_eq!(config.burst_size, 20);
+        assert_eq!(config.per_seconds, 1);
+    }
+
+    #[test]
+    fn rate_limit_config_creates_limiter() {
+        let config = RateLimitConfig::new(5, 1);
+        let limiter = config.create_limiter();
+
+        // First 5 requests should succeed
+        for _ in 0..5 {
+            assert!(limiter.check().is_ok());
+        }
+
+        // 6th request should fail
+        assert!(limiter.check().is_err());
+    }
+
+    #[tokio::test]
+    async fn rate_limit_middleware_allows_within_limit() {
+        use poem::{EndpointExt, Route, handler, test::TestClient};
+
+        #[handler]
+        async fn index() -> String {
+            "Hello".to_string()
+        }
+
+        let config = RateLimitConfig::new(5, 60);
+        let app = Route::new()
+            .at("/", poem::get(index))
+            .with(RateLimit::new(&config));
+        let cli = TestClient::new(app);
+
+        // First 5 requests should succeed
+        for _ in 0..5 {
+            let response = cli.get("/").send().await;
+            response.assert_status_is_ok();
+        }
+    }
+
+    #[tokio::test]
+    async fn rate_limit_middleware_blocks_over_limit() {
+        use poem::{EndpointExt, Route, handler, test::TestClient};
+
+        #[handler]
+        async fn index() -> String {
+            "Hello".to_string()
+        }
+
+        let config = RateLimitConfig::new(3, 60);
+        let app = Route::new()
+            .at("/", poem::get(index))
+            .with(RateLimit::new(&config));
+        let cli = TestClient::new(app);
+
+        // First 3 requests should succeed
+        for _ in 0..3 {
+            let response = cli.get("/").send().await;
+            response.assert_status_is_ok();
+        }
+
+        // 4th request should be rate limited
+        let response = cli.get("/").send().await;
+        response.assert_status(poem::http::StatusCode::TOO_MANY_REQUESTS);
+    }
+}

backend/src/presentation/mod.rs

@@ -0,0 +1,96 @@
+//! Presentation layer - API contracts and DTOs
+//!
+//! This module defines data transfer objects (DTOs) and API request/response types
+//! that form the public API contract. It translates between domain types and wire
+//! formats (JSON) for HTTP communication.
+//!
+//! # Current Status
+//!
+//! **Currently unused** - API handlers are currently in [`crate::route`] module using
+//! legacy structure. This module is prepared for future migration to proper hexagonal
+//! architecture with clear presentation layer separation.
+//!
+//! # Architecture Principles
+//!
+//! - **API-first design**: Define contracts before implementation
+//! - **DTO pattern**: Separate domain entities from API representations
+//! - **Validation at boundary**: Parse and validate input before domain layer
+//! - **OpenAPI integration**: Generate documentation from code
+//!
+//! # Planned Submodules
+//!
+//! ## `dto` - Data Transfer Objects
+//!
+//! - `relay_dto`: RelayResponse, RelayStatusResponse, BulkControlRequest
+//! - `label_dto`: UpdateLabelRequest, LabelResponse
+//! - `health_dto`: HealthResponse, DeviceStatusResponse
+//! - `error_dto`: ApiError, ValidationError (user-facing errors)
+//!
+//! ## `mapper` - Domain ↔ DTO Conversions
+//!
+//! - `relay_mapper`: Convert between Relay entity and RelayResponse
+//! - `error_mapper`: Translate domain errors to HTTP status codes
+//!
+//! ## `validator` - Input Validation
+//!
+//! - Request validation before domain layer
+//! - Parse DTOs into domain types (parse, don't validate principle)
+//!
+//! # DTO Design Pattern
+//!
+//! DTOs are separate from domain types to:
+//! 1. **Prevent domain leakage**: Domain types stay internal
+//! 2. **Enable versioning**: API can evolve without changing domain
+//! 3. **Control serialization**: Explicit JSON representation
+//! 4. **Validate at boundary**: Convert raw input to validated domain types
+//!
+//! # Example DTO Structure
+//!
+//! ```rust,ignore
+//! /// API response for relay status
+//! #[derive(Serialize, Deserialize, Object)]
+//! pub struct RelayResponse {
+//!     /// Relay ID (1-8)
+//!     pub id: u8,
+//!     /// Current state ("on" or "off")
+//!     pub state: String,
+//!     /// Optional custom label
+//!     pub label: Option<String>,
+//! }
+//!
+//! impl From<Relay> for RelayResponse {
+//!     fn from(relay: Relay) -> Self {
+//!         Self {
+//!             id: relay.id().value(),
+//!             state: relay.state().to_string(),
+//!             label: relay.label().map(|l| l.to_string()),
+//!         }
+//!     }
+//! }
+//!
+//! impl TryFrom<RelayResponse> for Relay {
+//!     type Error = ValidationError;
+//!
+//!     fn try_from(dto: RelayResponse) -> Result<Self, Self::Error> {
+//!         let id = RelayId::new(dto.id)?;
+//!         let state = RelayState::from_str(&dto.state)?;
+//!         let label = dto.label.map(RelayLabel::new).transpose()?;
+//!         Ok(Relay::new(id, state).with_label(label))
+//!     }
+//! }
+//! ```
+//!
+//! # Migration Plan
+//!
+//! Current API in [`crate::route`] will be migrated to this layer:
+//! 1. Define DTOs for all API endpoints
+//! 2. Implement domain <20> DTO mappers
+//! 3. Move API handlers to use DTOs
+//! 4. Generate OpenAPI specs from DTOs
+//! 5. Remove direct domain type exposure
+//!
+//! # References
+//!
+//! - Architecture: `specs/constitution.md` - API-First Design principle
+//! - API design: `specs/001-modbus-relay-control/plan.md` - Presentation layer tasks
+//! - Domain types: [`crate::domain`] - Types to be wrapped in DTOs

backend/src/route/health.rs

@@ -0,0 +1,38 @@
+//! Health check endpoint for monitoring service availability.
+
+use poem_openapi::{ApiResponse, OpenApi};
+
+use super::ApiCategory;
+
+#[derive(ApiResponse)]
+enum HealthResponse {
+    /// Success
+    #[oai(status = 200)]
+    Ok,
+    /// Too Many Requests - rate limit exceeded
+    #[oai(status = 429)]
+    #[allow(dead_code)]
+    TooManyRequests,
+}
+
+/// Health check API for monitoring service availability.
+#[derive(Default, Clone)]
+pub struct HealthApi;
+
+#[OpenApi(tag = "ApiCategory::Health")]
+impl HealthApi {
+    #[oai(path = "/health", method = "get")]
+    async fn ping(&self) -> HealthResponse {
+        tracing::event!(target: "backend::health", tracing::Level::DEBUG, "Accessing health-check endpoint");
+        HealthResponse::Ok
+    }
+}
+
+#[tokio::test]
+async fn health_check_works() {
+    let app = crate::get_test_app();
+    let cli = poem::test::TestClient::new(app);
+    let resp = cli.get("/api/health").send().await;
+    resp.assert_status_is_ok();
+    resp.assert_text("").await;
+}

backend/src/route/meta.rs

@@ -0,0 +1,86 @@
+//! Application metadata endpoint for retrieving version and name information.
+
+use poem::Result;
+use poem_openapi::{ApiResponse, Object, OpenApi, payload::Json};
+
+use super::ApiCategory;
+use crate::settings::ApplicationSettings;
+
+#[derive(Object, Debug, Clone, serde::Serialize, serde::Deserialize)]
+struct Meta {
+    version: String,
+    name: String,
+}
+
+impl From<&MetaApi> for Meta {
+    fn from(value: &MetaApi) -> Self {
+        let version = value.version.clone();
+        let name = value.name.clone();
+        Self { version, name }
+    }
+}
+
+#[derive(ApiResponse)]
+enum MetaResponse {
+    /// Success
+    #[oai(status = 200)]
+    Meta(Json<Meta>),
+    /// Too Many Requests - rate limit exceeded
+    #[oai(status = 429)]
+    #[allow(dead_code)]
+    TooManyRequests,
+}
+
+/// API for retrieving application metadata (name and version).
+#[derive(Clone)]
+pub struct MetaApi {
+    name: String,
+    version: String,
+}
+
+impl From<&ApplicationSettings> for MetaApi {
+    fn from(value: &ApplicationSettings) -> Self {
+        let name = value.name.clone();
+        let version = value.version.clone();
+        Self { name, version }
+    }
+}
+
+#[OpenApi(tag = "ApiCategory::Meta")]
+impl MetaApi {
+    #[oai(path = "/meta", method = "get")]
+    async fn meta(&self) -> Result<MetaResponse> {
+        tracing::event!(target: "backend::meta", tracing::Level::DEBUG, "Accessing meta endpoint");
+        Ok(MetaResponse::Meta(Json(self.into())))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[tokio::test]
+    async fn meta_endpoint_returns_correct_data() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+        let resp = cli.get("/api/meta").send().await;
+        resp.assert_status_is_ok();
+
+        let json_value: serde_json::Value = resp.json().await.value().deserialize();
+
+        assert!(
+            json_value.get("version").is_some(),
+            "Response should have version field"
+        );
+        assert!(
+            json_value.get("name").is_some(),
+            "Response should have name field"
+        );
+    }
+
+    #[tokio::test]
+    async fn meta_endpoint_returns_200_status() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+        let resp = cli.get("/api/meta").send().await;
+        resp.assert_status_is_ok();
+    }
+}

backend/src/route/mod.rs

@@ -0,0 +1,37 @@
+//! API route handlers for the backend server.
+//!
+//! This module contains all the HTTP endpoint handlers organized by functionality:
+//! - Health checks
+//! - Application metadata
+
+use poem_openapi::Tags;
+
+mod health;
+mod meta;
+
+use crate::settings::Settings;
+
+#[derive(Tags)]
+enum ApiCategory {
+    Health,
+    Meta,
+}
+
+pub(crate) struct Api {
+    health: health::HealthApi,
+    meta: meta::MetaApi,
+}
+
+impl From<&Settings> for Api {
+    fn from(value: &Settings) -> Self {
+        let health = health::HealthApi;
+        let meta = meta::MetaApi::from(&value.application);
+        Self { health, meta }
+    }
+}
+
+impl Api {
+    pub fn apis(self) -> (health::HealthApi, meta::MetaApi) {
+        (self.health, self.meta)
+    }
+}

backend/src/settings.rs

@@ -0,0 +1,339 @@
+//! Application configuration settings.
+//!
+//! This module provides configuration structures that can be loaded from:
+//! - YAML configuration files (base.yaml and environment-specific files)
+//! - Environment variables (prefixed with APP__)
+//!
+//! Settings include application details, Modbus connection parameters, relay configuration,
+//! rate limiting, and environment settings.
+
+/// Application configuration settings.
+///
+/// Loads configuration from YAML files and environment variables.
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct Settings {
+    /// Application-specific settings (name, version, host, port, etc.)
+    pub application: ApplicationSettings,
+    /// Debug mode flag
+    pub debug: bool,
+    /// Frontend URL for CORS configuration
+    pub frontend_url: String,
+    /// Rate limiting configuration
+    #[serde(default)]
+    pub rate_limit: RateLimitSettings,
+    /// Modbus configuration
+    pub modbus: ModbusSettings,
+    /// Relay configuration
+    pub relay: RelaySettings,
+}
+
+impl Settings {
+    /// Creates a new `Settings` instance by loading configuration from files and environment variables.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `config::ConfigError` if:
+    /// - Configuration files cannot be read or parsed
+    /// - Required configuration values are missing
+    /// - Configuration values cannot be deserialized into the expected types
+    ///
+    /// # Panics
+    ///
+    /// Panics if:
+    /// - The current directory cannot be determined
+    /// - The `APP_ENVIRONMENT` variable contains an invalid value (not "dev", "development", "prod", or "production")
+    pub fn new() -> Result<Self, config::ConfigError> {
+        // Use CARGO_MANIFEST_DIR to reliably locate settings regardless of where cargo is run from
+        let base_path = std::env::var("CARGO_MANIFEST_DIR").map_or_else(
+            // Fallback to current_dir for non-cargo builds
+            |_| std::env::current_dir().expect("Failed to determine the current directory"),
+            std::path::PathBuf::from,
+        );
+        println!("Reading settings from directory {}", base_path.display());
+        let settings_directory = base_path.join("settings");
+        let environment: Environment = std::env::var("APP_ENVIRONMENT")
+            .unwrap_or_else(|_| "dev".into())
+            .try_into()
+            .expect("Failed to parse APP_ENVIRONMENT");
+        let environment_filename = format!("{environment}.yaml");
+        // Lower = takes precedence
+        let settings = config::Config::builder()
+            .add_source(config::File::from(settings_directory.join("base.yaml")))
+            .add_source(config::File::from(
+                settings_directory.join(environment_filename),
+            ))
+            .add_source(
+                config::Environment::with_prefix("APP")
+                    .prefix_separator("__")
+                    .separator("__"),
+            )
+            .build()?;
+        settings.try_deserialize()
+    }
+}
+
+/// Application-specific configuration settings.
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct ApplicationSettings {
+    /// Application name
+    pub name: String,
+    /// Application version
+    pub version: String,
+    /// Port to bind to
+    pub port: u16,
+    /// Host address to bind to
+    pub host: String,
+    /// Base URL of the application
+    pub base_url: String,
+    /// Protocol (http or https)
+    pub protocol: String,
+}
+
+/// Application environment.
+#[derive(Debug, PartialEq, Eq, Default)]
+pub enum Environment {
+    /// Development environment
+    #[default]
+    Development,
+    /// Production environment
+    Production,
+}
+
+impl std::fmt::Display for Environment {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let self_str = match self {
+            Self::Development => "development",
+            Self::Production => "production",
+        };
+        write!(f, "{self_str}")
+    }
+}
+
+impl TryFrom<String> for Environment {
+    type Error = String;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::try_from(value.as_str())
+    }
+}
+
+impl TryFrom<&str> for Environment {
+    type Error = String;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        match value.to_lowercase().as_str() {
+            "development" | "dev" => Ok(Self::Development),
+            "production" | "prod" => Ok(Self::Production),
+            other => Err(format!(
+                "{other} is not a supported environment. Use either `development` or `production`"
+            )),
+        }
+    }
+}
+
+/// Rate limiting configuration.
+#[derive(Debug, serde::Deserialize, Clone)]
+pub struct RateLimitSettings {
+    /// Whether rate limiting is enabled
+    #[serde(default = "default_rate_limit_enabled")]
+    pub enabled: bool,
+    /// Maximum number of requests allowed in the time window (burst size)
+    #[serde(default = "default_burst_size")]
+    pub burst_size: u32,
+    /// Time window in seconds for rate limiting
+    #[serde(default = "default_per_seconds")]
+    pub per_seconds: u64,
+}
+
+impl Default for RateLimitSettings {
+    fn default() -> Self {
+        Self {
+            enabled: default_rate_limit_enabled(),
+            burst_size: default_burst_size(),
+            per_seconds: default_per_seconds(),
+        }
+    }
+}
+
+const fn default_rate_limit_enabled() -> bool {
+    true
+}
+
+const fn default_burst_size() -> u32 {
+    100
+}
+
+const fn default_per_seconds() -> u64 {
+    60
+}
+
+/// Modbus TCP connection configuration.
+///
+/// Configures the connection parameters for communicating with the Modbus relay device
+/// using Modbus RTU over TCP protocol.
+#[derive(Debug, serde::Deserialize, Clone)]
+pub struct ModbusSettings {
+    /// IP address or hostname of the Modbus device
+    pub host: String,
+    /// TCP port for Modbus communication (standard Modbus TCP port is 502)
+    pub port: u16,
+    /// Modbus slave/device ID (unit identifier)
+    pub slave_id: u8,
+    /// Operation timeout in seconds
+    pub timeout_secs: u8,
+}
+
+impl Default for ModbusSettings {
+    fn default() -> Self {
+        Self {
+            host: "192.168.0.200".to_string(),
+            port: 502,
+            slave_id: 0,
+            timeout_secs: 5,
+        }
+    }
+}
+
+/// Relay control configuration.
+///
+/// Configures parameters for relay management and labeling.
+#[derive(Debug, serde::Deserialize, Clone)]
+pub struct RelaySettings {
+    /// Maximum length for custom relay labels (in characters)
+    pub label_max_length: u8,
+}
+
+impl Default for RelaySettings {
+    fn default() -> Self {
+        Self {
+            label_max_length: 8,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn environment_display_development() {
+        let env = Environment::Development;
+        assert_eq!(env.to_string(), "development");
+    }
+
+    #[test]
+    fn environment_display_production() {
+        let env = Environment::Production;
+        assert_eq!(env.to_string(), "production");
+    }
+
+    #[test]
+    fn environment_from_str_development() {
+        assert_eq!(
+            Environment::try_from("development").unwrap(),
+            Environment::Development
+        );
+        assert_eq!(
+            Environment::try_from("dev").unwrap(),
+            Environment::Development
+        );
+        assert_eq!(
+            Environment::try_from("Development").unwrap(),
+            Environment::Development
+        );
+        assert_eq!(
+            Environment::try_from("DEV").unwrap(),
+            Environment::Development
+        );
+    }
+
+    #[test]
+    fn environment_from_str_production() {
+        assert_eq!(
+            Environment::try_from("production").unwrap(),
+            Environment::Production
+        );
+        assert_eq!(
+            Environment::try_from("prod").unwrap(),
+            Environment::Production
+        );
+        assert_eq!(
+            Environment::try_from("Production").unwrap(),
+            Environment::Production
+        );
+        assert_eq!(
+            Environment::try_from("PROD").unwrap(),
+            Environment::Production
+        );
+    }
+
+    #[test]
+    fn environment_from_str_invalid() {
+        let result = Environment::try_from("invalid");
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("not a supported environment"));
+    }
+
+    #[test]
+    fn environment_from_string_development() {
+        assert_eq!(
+            Environment::try_from("development".to_string()).unwrap(),
+            Environment::Development
+        );
+    }
+
+    #[test]
+    fn environment_from_string_production() {
+        assert_eq!(
+            Environment::try_from("production".to_string()).unwrap(),
+            Environment::Production
+        );
+    }
+
+    #[test]
+    fn environment_from_string_invalid() {
+        let result = Environment::try_from("invalid".to_string());
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn environment_default_is_development() {
+        let env = Environment::default();
+        assert_eq!(env, Environment::Development);
+    }
+
+    #[test]
+    fn rate_limit_settings_default() {
+        let settings = RateLimitSettings::default();
+        assert!(settings.enabled);
+        assert_eq!(settings.burst_size, 100);
+        assert_eq!(settings.per_seconds, 60);
+    }
+
+    #[test]
+    fn rate_limit_settings_deserialize_full() {
+        let json = r#"{"enabled": true, "burst_size": 50, "per_seconds": 30}"#;
+        let settings: RateLimitSettings = serde_json::from_str(json).unwrap();
+        assert!(settings.enabled);
+        assert_eq!(settings.burst_size, 50);
+        assert_eq!(settings.per_seconds, 30);
+    }
+
+    #[test]
+    fn rate_limit_settings_deserialize_partial() {
+        let json = r#"{"enabled": false}"#;
+        let settings: RateLimitSettings = serde_json::from_str(json).unwrap();
+        assert!(!settings.enabled);
+        assert_eq!(settings.burst_size, 100); // default
+        assert_eq!(settings.per_seconds, 60); // default
+    }
+
+    #[test]
+    fn rate_limit_settings_deserialize_empty() {
+        let json = "{}";
+        let settings: RateLimitSettings = serde_json::from_str(json).unwrap();
+        assert!(settings.enabled); // default
+        assert_eq!(settings.burst_size, 100); // default
+        assert_eq!(settings.per_seconds, 60); // default
+    }
+}

backend/src/startup.rs

@@ -0,0 +1,229 @@
+//! Application startup and server configuration.
+//!
+//! This module handles:
+//! - Building the application with routes and middleware
+//! - Setting up the OpenAPI service and Swagger UI
+//! - Configuring CORS
+//! - Starting the HTTP server
+
+use poem::middleware::{AddDataEndpoint, Cors, CorsEndpoint};
+use poem::{EndpointExt, Route};
+use poem_openapi::OpenApiService;
+
+use crate::{
+    middleware::rate_limit::{RateLimit, RateLimitConfig},
+    route::Api,
+    settings::Settings,
+};
+
+use crate::middleware::rate_limit::RateLimitEndpoint;
+
+type Server = poem::Server<poem::listener::TcpListener<String>, std::convert::Infallible>;
+/// The configured application with rate limiting, CORS, and settings data.
+pub type App = AddDataEndpoint<CorsEndpoint<RateLimitEndpoint<Route>>, Settings>;
+
+/// Application builder that holds the server configuration before running.
+pub struct Application {
+    server: Server,
+    app: poem::Route,
+    host: String,
+    port: u16,
+    settings: Settings,
+}
+
+/// A fully configured application ready to run.
+pub struct RunnableApplication {
+    server: Server,
+    app: App,
+}
+
+impl RunnableApplication {
+    /// Runs the application server.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `std::io::Error` if the server fails to start or encounters
+    /// an I/O error during runtime (e.g., port already in use, network issues).
+    pub async fn run(self) -> Result<(), std::io::Error> {
+        self.server.run(self.app).await
+    }
+}
+
+impl From<RunnableApplication> for App {
+    fn from(value: RunnableApplication) -> Self {
+        value.app
+    }
+}
+
+impl From<Application> for RunnableApplication {
+    fn from(value: Application) -> Self {
+        // Configure rate limiting based on settings
+        let rate_limit_config = if value.settings.rate_limit.enabled {
+            tracing::event!(
+                target: "backend::startup",
+                tracing::Level::INFO,
+                burst_size = value.settings.rate_limit.burst_size,
+                per_seconds = value.settings.rate_limit.per_seconds,
+                "Rate limiting enabled"
+            );
+            RateLimitConfig::new(
+                value.settings.rate_limit.burst_size,
+                value.settings.rate_limit.per_seconds,
+            )
+        } else {
+            tracing::event!(
+                target: "backend::startup",
+                tracing::Level::INFO,
+                "Rate limiting disabled (using very high limits)"
+            );
+            // Use very high limits to effectively disable rate limiting
+            RateLimitConfig::new(u32::MAX, 1)
+        };
+
+        let app = value
+            .app
+            .with(RateLimit::new(&rate_limit_config))
+            .with(Cors::new())
+            .data(value.settings);
+
+        let server = value.server;
+        Self { server, app }
+    }
+}
+
+impl Application {
+    fn setup_app(settings: &Settings) -> poem::Route {
+        let api_service = OpenApiService::new(
+            Api::from(settings).apis(),
+            settings.application.clone().name,
+            settings.application.clone().version,
+        )
+        .url_prefix("/api");
+        let ui = api_service.swagger_ui();
+        poem::Route::new()
+            .nest("/api", api_service.clone())
+            .nest("/specs", api_service.spec_endpoint_yaml())
+            .nest("/", ui)
+    }
+
+    fn setup_server(
+        settings: &Settings,
+        tcp_listener: Option<poem::listener::TcpListener<String>>,
+    ) -> Server {
+        let tcp_listener = tcp_listener.unwrap_or_else(|| {
+            let address = format!(
+                "{}:{}",
+                settings.application.host, settings.application.port
+            );
+            poem::listener::TcpListener::bind(address)
+        });
+        poem::Server::new(tcp_listener)
+    }
+
+    /// Builds a new application with the given settings and optional TCP listener.
+    ///
+    /// If no listener is provided, one will be created based on the settings.
+    #[must_use]
+    pub fn build(
+        settings: Settings,
+        tcp_listener: Option<poem::listener::TcpListener<String>>,
+    ) -> Self {
+        let port = settings.application.port;
+        let host = settings.application.clone().host;
+        let app = Self::setup_app(&settings);
+        let server = Self::setup_server(&settings, tcp_listener);
+        Self {
+            server,
+            app,
+            host,
+            port,
+            settings,
+        }
+    }
+
+    /// Converts the application into a runnable application.
+    #[must_use]
+    pub fn make_app(self) -> RunnableApplication {
+        self.into()
+    }
+
+    /// Returns the host address the application is configured to bind to.
+    #[must_use]
+    pub fn host(&self) -> String {
+        self.host.clone()
+    }
+
+    /// Returns the port the application is configured to bind to.
+    #[must_use]
+    pub const fn port(&self) -> u16 {
+        self.port
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn create_test_settings() -> Settings {
+        Settings {
+            application: crate::settings::ApplicationSettings {
+                name: "test-app".to_string(),
+                version: "1.0.0".to_string(),
+                port: 8080,
+                host: "127.0.0.1".to_string(),
+                base_url: "http://localhost:8080".to_string(),
+                protocol: "http".to_string(),
+            },
+            debug: false,
+            frontend_url: "http://localhost:3000".to_string(),
+            rate_limit: crate::settings::RateLimitSettings {
+                enabled: false,
+                burst_size: 100,
+                per_seconds: 60,
+            },
+            modbus: crate::settings::ModbusSettings::default(),
+            relay: crate::settings::RelaySettings::default(),
+        }
+    }
+
+    #[test]
+    fn application_build_and_host() {
+        let settings = create_test_settings();
+        let app = Application::build(settings.clone(), None);
+        assert_eq!(app.host(), settings.application.host);
+    }
+
+    #[test]
+    fn application_build_and_port() {
+        let settings = create_test_settings();
+        let app = Application::build(settings, None);
+        assert_eq!(app.port(), 8080);
+    }
+
+    #[test]
+    fn application_host_returns_correct_value() {
+        let settings = create_test_settings();
+        let app = Application::build(settings, None);
+        assert_eq!(app.host(), "127.0.0.1");
+    }
+
+    #[test]
+    fn application_port_returns_correct_value() {
+        let settings = create_test_settings();
+        let app = Application::build(settings, None);
+        assert_eq!(app.port(), 8080);
+    }
+
+    #[test]
+    fn application_with_custom_listener() {
+        let settings = create_test_settings();
+        let tcp_listener =
+            std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind random port");
+        let port = tcp_listener.local_addr().unwrap().port();
+        let listener = poem::listener::TcpListener::bind(format!("127.0.0.1:{port}"));
+
+        let app = Application::build(settings, Some(listener));
+        assert_eq!(app.host(), "127.0.0.1");
+        assert_eq!(app.port(), 8080);
+    }
+}

backend/src/telemetry.rs

@@ -0,0 +1,69 @@
+//! Logging and tracing configuration.
+//!
+//! This module provides utilities for setting up structured logging using the tracing crate.
+//! Supports both pretty-printed logs for development and JSON logs for production.
+
+use tracing_subscriber::layer::SubscriberExt;
+
+/// Creates a tracing subscriber configured for the given debug mode.
+///
+/// In debug mode, logs are pretty-printed to stdout.
+/// In production mode, logs are output as JSON.
+#[must_use]
+pub fn get_subscriber(debug: bool) -> impl tracing::Subscriber + Send + Sync {
+    let env_filter = if debug { "debug" } else { "info" }.to_string();
+    let env_filter = tracing_subscriber::EnvFilter::try_from_default_env()
+        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new(env_filter));
+    let stdout_log = tracing_subscriber::fmt::layer().pretty();
+    let subscriber = tracing_subscriber::Registry::default()
+        .with(env_filter)
+        .with(stdout_log);
+    let json_log = if debug {
+        None
+    } else {
+        Some(tracing_subscriber::fmt::layer().json())
+    };
+    subscriber.with(json_log)
+}
+
+/// Initializes the global tracing subscriber.
+///
+/// # Panics
+///
+/// Panics if:
+/// - A global subscriber has already been set
+/// - The subscriber cannot be set as the global default
+pub fn init_subscriber(subscriber: impl tracing::Subscriber + Send + Sync) {
+    tracing::subscriber::set_global_default(subscriber).expect("Failed to set subscriber");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn get_subscriber_debug_mode() {
+        let subscriber = get_subscriber(true);
+        // If we can create the subscriber without panicking, the test passes
+        // We can't easily inspect the subscriber's internals, but we can verify it's created
+        let _ = subscriber;
+    }
+
+    #[test]
+    fn get_subscriber_production_mode() {
+        let subscriber = get_subscriber(false);
+        // If we can create the subscriber without panicking, the test passes
+        let _ = subscriber;
+    }
+
+    #[test]
+    fn get_subscriber_creates_valid_subscriber() {
+        // Test both debug and non-debug modes create valid subscribers
+        let debug_subscriber = get_subscriber(true);
+        let prod_subscriber = get_subscriber(false);
+
+        // Basic smoke test - if these are created without panicking, they're valid
+        let _ = debug_subscriber;
+        let _ = prod_subscriber;
+    }
+}