feat: initialization migration to Nuxt + Backend

This commit initializes both the Nuxt frontend and the Rust backend of
the new version of phundrak.com

backend/.tarpaulin.ci.toml

@@ -0,0 +1,6 @@
+[all]
+out = ["Xml"]
+target-dir = "coverage"
+output-dir = "coverage"
+fail-under = 60
+exclude-files = ["target/*"]

backend/.tarpaulin.local.toml

@@ -0,0 +1,7 @@
+[all]
+out = ["Html", "Lcov"]
+skip-clean = true
+target-dir = "coverage"
+output-dir = "coverage"
+fail-under = 60
+exclude-files = ["target/*"]

backend/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "phundrak-dot-com-backend"
+version = "0.1.0"
+edition = "2024"
+publish = false
+authors = ["Lucien Cartier-Tilet <lucien@phundrak.com>"]
+license = "AGPL-3.0-only"
+
+[lib]
+path = "src/lib.rs"
+
+[[bin]]
+path = "src/main.rs"
+name = "backend"
+
+[dependencies]
+chrono = { version = "0.4.42", features = ["serde"] }
+config = { version = "0.15.18", features = ["yaml"] }
+dotenvy = "0.15.7"
+lettre = { version = "0.11.19", default-features = false, features = ["builder", "hostname", "pool", "rustls-tls", "tokio1", "tokio1-rustls-tls", "smtp-transport"] }
+poem = { version = "3.1.12", default-features = false, features = ["csrf", "rustls", "test"] }
+poem-openapi = { version = "5.1.16", features = ["chrono", "swagger-ui"] }
+serde = "1.0.228"
+serde_json = "1.0.145"
+thiserror = "2.0.17"
+tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread"] }
+tracing = "0.1.41"
+tracing-subscriber = { version = "0.3.20", features = ["fmt", "std", "env-filter", "registry", "json", "tracing-log"] }
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tarpaulin_include)'] }

backend/README.md

@@ -0,0 +1,143 @@
+# phundrak.com Backend
+
+The backend for [phundrak.com](https://phundrak.com), built with Rust and the [Poem](https://github.com/poem-web/poem) web framework.
+
+## Features
+
+- **RESTful API** with OpenAPI documentation
+- **Type-safe routing** using Poem's declarative API
+- **Structured logging** with `tracing`
+- **Strict linting** for code quality and safety
+- **Comprehensive testing** with integration test support
+
+## Development
+
+### Prerequisites
+
+- Rust (latest stable version recommended)
+- Cargo (comes with Rust)
+
+### Running the Server
+
+To start the development server:
+
+```bash
+cargo run
+```
+
+The server will start on the configured port (check your configuration for details).
+
+### Building
+
+For development builds:
+
+```bash
+cargo build
+```
+
+For optimized production builds:
+
+```bash
+cargo build --release
+```
+
+The compiled binary will be at `target/release/backend`.
+
+## Testing
+
+Run all tests:
+
+```bash
+cargo test
+```
+
+Run a specific test:
+
+```bash
+cargo test <test_name>
+```
+
+Run tests with output:
+
+```bash
+cargo test -- --nocapture
+```
+
+## Code Quality
+
+### Linting
+
+This project uses strict Clippy linting rules:
+
+- `#![deny(clippy::all)]`
+- `#![deny(clippy::pedantic)]`
+- `#![deny(clippy::nursery)]`
+
+Run Clippy to check for issues:
+
+```bash
+cargo clippy --all-targets
+```
+
+### Continuous Checking with Bacon
+
+For continuous testing and linting during development, use [bacon](https://dystroy.org/bacon/):
+
+```bash
+bacon
+```
+
+This will watch your files and automatically run clippy or tests on changes.
+
+## Code Style
+
+### Error Handling
+
+- Use `thiserror` for custom error types
+- Always return `Result` types for fallible operations
+- Use descriptive error messages
+
+### Logging
+
+- Use `tracing::event!` for logging
+- Always set `target: "backend"`
+- Use appropriate log levels (trace, debug, info, warn, error)
+
+Example:
+```rust
+tracing::event!(target: "backend", tracing::Level::INFO, "Server started");
+```
+
+### Imports
+
+Organize imports in three groups:
+1. Standard library (`std::*`)
+2. External crates
+3. Local modules
+
+Use explicit paths (e.g., `poem_openapi::ApiResponse` instead of wildcards).
+
+### Testing
+
+- Use `#[cfg(test)]` module blocks
+- Leverage Poem's test utilities for endpoint testing
+- Use random TCP listeners for integration tests to avoid port conflicts
+
+## Project Structure
+
+```
+backend/
+├── src/
+│   ├── main.rs          # Application entry point
+│   ├── api/             # API endpoints
+│   ├── models/          # Data models
+│   ├── services/        # Business logic
+│   └── utils/           # Utility functions
+├── tests/               # Integration tests
+├── Cargo.toml           # Dependencies and metadata
+└── README.md            # This file
+```
+
+## License
+
+See the root repository for license information.

backend/bacon.toml

@@ -0,0 +1,84 @@
+# This is a configuration file for the bacon tool
+#
+# Bacon repository: https://github.com/Canop/bacon
+# Complete help on configuration: https://dystroy.org/bacon/config/
+# You can also check bacon's own bacon.toml file
+#  as an example: https://github.com/Canop/bacon/blob/main/bacon.toml
+
+default_job = "clippy-all"
+
+[jobs.check]
+command = ["cargo", "check", "--color", "always"]
+need_stdout = false
+
+[jobs.check-all]
+command = ["cargo", "check", "--all-targets", "--color", "always"]
+need_stdout = false
+
+# Run clippy on the default target
+[jobs.clippy]
+command = [
+    "cargo", "clippy",
+    "--color", "always",
+]
+need_stdout = false
+
+[jobs.clippy-all]
+command = [
+    "cargo", "clippy",
+    "--all-targets",
+    "--color", "always",
+]
+need_stdout = false
+
+[jobs.test]
+command = [
+    "cargo", "test", "--color", "always",
+    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
+]
+need_stdout = true
+
+[jobs.doc]
+command = ["cargo", "doc", "--color", "always", "--no-deps"]
+need_stdout = false
+
+# If the doc compiles, then it opens in your browser and bacon switches
+# to the previous job
+[jobs.doc-open]
+command = ["cargo", "doc", "--color", "always", "--no-deps", "--open"]
+need_stdout = false
+on_success = "back" # so that we don't open the browser at each change
+
+# You can run your application and have the result displayed in bacon,
+# *if* it makes sense for this crate.
+# Don't forget the `--color always` part or the errors won't be
+# properly parsed.
+# If your program never stops (eg a server), you may set `background`
+# to false to have the cargo run output immediately displayed instead
+# of waiting for program's end.
+[jobs.run]
+command = [
+    "cargo", "run",
+    "--color", "always",
+    # put launch parameters for your program behind a `--` separator
+]
+need_stdout = true
+allow_warnings = true
+background = true
+
+# This parameterized job runs the example of your choice, as soon
+# as the code compiles.
+# Call it as
+#    bacon ex -- my-example
+[jobs.ex]
+command = ["cargo", "run", "--color", "always", "--example"]
+need_stdout = true
+allow_warnings = true
+
+# You may define here keybindings that would be specific to
+# a project, for example a shortcut to launch a specific job.
+# Shortcuts to internal functions (scrolling, toggling, etc.)
+# should go in your personal global prefs.toml file instead.
+[keybindings]
+# alt-m = "job:my-job"
+c = "job:clippy-all" # comment this to have 'c' run clippy on only the default target

backend/deny.toml

@@ -0,0 +1,51 @@
+[output]
+feature-depth = 1
+
+[advisories]
+ignore = []
+
+[licenses]
+# List of explicitly allowed licenses
+# See https://spdx.org/licenses/ for list of possible licenses
+allow = [
+  "0BSD",
+  "AGPL-3.0-only",
+  "Apache-2.0 WITH LLVM-exception",
+  "Apache-2.0",
+  "BSD-3-Clause",
+  "CDLA-Permissive-2.0",
+  "ISC",
+  "MIT",
+  "MPL-2.0",
+  "OpenSSL",
+  "Unicode-3.0",
+  "Zlib",
+]
+confidence-threshold = 0.8
+exceptions = []
+
+[licenses.private]
+ignore = false
+registries = []
+
+[bans]
+multiple-versions = "allow"
+wildcards = "allow"
+highlight = "all"
+workspace-default-features = "allow"
+external-default-features = "allow"
+allow = []
+deny = []
+skip = []
+skip-tree = []
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "deny"
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+allow-git = []
+
+[sources.allow-org]
+github = []
+gitlab = []
+bitbucket = []

backend/justfile

@@ -0,0 +1,48 @@
+default: run
+
+run:
+	cargo run
+
+run-release:
+	cargo run --release
+
+format:
+	cargo fmt --all
+
+format-check:
+	cargo fmt --check --all
+
+audit:
+	cargo deny
+
+build:
+	cargo build
+
+build-release:
+	cargo build --release
+
+lint:
+	cargo clippy --all-targets
+
+release-build:
+	cargo build --release
+
+release-run:
+	cargo run --release
+
+test:
+	cargo test
+
+coverage:
+	mkdir -p coverage
+	cargo tarpaulin --config .tarpaulin.local.toml
+
+coverage-ci:
+	mkdir -p coverage
+	cargo tarpaulin --config .tarpaulin.ci.toml
+
+check-all: format-check lint coverage audit
+
+## Local Variables:
+## mode: makefile
+## End:

backend/settings/base.yaml

@@ -0,0 +1,9 @@
+application:
+  port: 3100
+  version: "0.1.0"
+
+email:
+  host: localhost
+  user: user
+  from: Contact Form <noreply@example.com>
+  password: hunter2

backend/settings/development.yaml

@@ -0,0 +1,8 @@
+frontend_url: http://localhost:3000
+debug: true
+
+application:
+  protocol: http
+  host: 127.0.0.1
+  base_url: http://127.0.0.1:3100
+  name: "com.phundrak.backend.prod"

backend/settings/production.yaml

@@ -0,0 +1,8 @@
+debug: false
+frontend_url: ""
+
+application:
+  name: "com.phundrak.backend.prod"
+  protocol: https
+  host: 0.0.0.0
+  base_url: ""

backend/shell.nix

@@ -0,0 +1,77 @@
+{
+  inputs,
+  pkgs,
+  system,
+  self,
+  rust-overlay,
+  ...
+}: let
+  overlays = [(import rust-overlay)];
+  rustPkgs = import inputs.nixpkgs {inherit system overlays;};
+  rustVersion = rustPkgs.rust-bin.stable.latest.default;
+in
+  inputs.devenv.lib.mkShell {
+    inherit inputs pkgs;
+    modules = [
+      {
+        devenv.root = let
+          devenvRootFileContent = builtins.readFile "${self}/.devenv-root";
+        in
+          pkgs.lib.mkIf (devenvRootFileContent != "") devenvRootFileContent;
+      }
+      {
+        packages = with rustPkgs; [
+          (rustVersion.override {
+            extensions = [
+              "clippy"
+              "rust-src"
+              "rust-analyzer"
+              "rustfmt"
+            ];
+          })
+          bacon
+          cargo-deny
+          cargo-shuttle
+          cargo-tarpaulin
+          cargo-watch
+          flyctl
+          just
+          tombi # TOML lsp server
+          vscode-langservers-extracted
+        ];
+
+        services.mailpit = {
+          enable = true;
+          # HTTP interface for viewing emails
+          uiListenAddress = "127.0.0.1:8025";
+          # SMTP server for receiving emails
+          smtpListenAddress = "127.0.0.1:1025";
+        };
+
+        processes.run.exec = "cargo watch -x run";
+
+        enterShell = ''
+          echo "🦀 Rust backend development environment loaded!"
+          echo "📦 Rust version: $(rustc --version)"
+          echo "📦 Cargo version: $(cargo --version)"
+          echo ""
+          echo "Available tools:"
+          echo "  - rust-analyzer (LSP)"
+          echo "  - clippy (linter)"
+          echo "  - rustfmt (formatter)"
+          echo "  - bacon (continuous testing/linting)"
+          echo "  - cargo-deny (dependency checker)"
+          echo "  - cargo-tarpaulin (code coverage)"
+          echo ""
+          echo "📧 Mailpit service:"
+          echo "  - SMTP server: 127.0.0.1:1025"
+          echo "  - Web UI: http://127.0.0.1:8025"
+          echo ""
+          echo "🚀 Quick start:"
+          echo "  Run 'devenv up' to launch:"
+          echo "    - Mailpit service (email testing)"
+          echo "    - Backend with 'cargo watch -x run' (auto-reload)"
+        '';
+      }
+    ];
+  }

backend/src/lib.rs

@@ -0,0 +1,64 @@
+#![deny(clippy::all)]
+#![deny(clippy::pedantic)]
+#![deny(clippy::nursery)]
+#![allow(clippy::missing_panics_doc)]
+#![allow(clippy::missing_errors_doc)]
+#![allow(clippy::unused_async)]
+
+pub mod route;
+pub mod settings;
+pub mod startup;
+pub mod telemetry;
+
+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://{}:{}/docs",
+        application.host(),
+        application.port()
+    );
+    application
+}
+
+#[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,5 @@
+#[cfg(not(tarpaulin_include))]
+#[tokio::main]
+async fn main() -> Result<(), std::io::Error> {
+    phundrak_dot_com_backend::run(None).await
+}

backend/src/route/health.rs

@@ -0,0 +1,29 @@
+use poem_openapi::{ApiResponse, OpenApi};
+
+use super::ApiCategory;
+
+#[derive(ApiResponse)]
+enum HealthResponse {
+    #[oai(status = 200)]
+    Ok,
+}
+
+pub struct HealthApi;
+
+#[OpenApi(prefix_path = "/v1/health-check", tag = "ApiCategory::Health")]
+impl HealthApi {
+    #[oai(path = "/", method = "get")]
+    async fn ping(&self) -> HealthResponse {
+        tracing::event!(target: "backend", 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("/v1/health-check").send().await;
+    resp.assert_status_is_ok();
+    resp.assert_text("").await;
+}

backend/src/route/meta.rs

@@ -0,0 +1,86 @@
+use poem::Result;
+use poem_openapi::{ApiResponse, Object, OpenApi, payload::Json};
+
+use super::ApiCategory;
+use crate::settings::Settings;
+
+#[derive(Object, Debug, Clone, serde::Serialize, serde::Deserialize)]
+struct Meta {
+    version: String,
+    name: String,
+}
+
+impl From<poem::web::Data<&Settings>> for Meta {
+    fn from(value: poem::web::Data<&Settings>) -> Self {
+        let version = value.application.version.clone();
+        let name = value.application.name.clone();
+        Self { version, name }
+    }
+}
+
+#[derive(ApiResponse)]
+enum MetaResponse {
+    #[oai(status = 200)]
+    Meta(Json<Meta>),
+}
+
+pub struct MetaApi;
+
+#[OpenApi(prefix_path = "/v1/meta", tag = "ApiCategory::Meta")]
+impl MetaApi {
+    #[oai(path = "/", method = "get")]
+    async fn meta(&self, settings: poem::web::Data<&Settings>) -> Result<MetaResponse> {
+        tracing::event!(target: "backend", tracing::Level::DEBUG, "Accessing meta endpoint");
+        Ok(MetaResponse::Meta(Json(settings.into())))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::settings::ApplicationSettings;
+
+    #[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("/v1/meta").send().await;
+        resp.assert_status_is_ok();
+
+        // let json = resp.0.into_json().await;
+        // assert!(json.is_ok(), "Response should be valid JSON");
+        // let json_value: serde_json::Value = json.unwrap();
+
+        // 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("/v1/meta").send().await;
+        resp.assert_status_is_ok();
+    }
+
+    #[test]
+    fn meta_from_settings_conversion() {
+        let settings = Settings {
+            application: 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,
+            email: crate::settings::EmailSettings::default(),
+            frontend_url: "http://localhost:3000".to_string(),
+        };
+
+        let meta: Meta = poem::web::Data(&settings).into();
+        assert_eq!(meta.name, "test-app");
+        assert_eq!(meta.version, "1.0.0");
+    }
+}

backend/src/route/mod.rs

@@ -0,0 +1,18 @@
+use poem_openapi::{OpenApi, Tags};
+
+mod health;
+pub use health::HealthApi;
+
+mod meta;
+pub use meta::MetaApi;
+
+#[derive(Tags)]
+enum ApiCategory {
+    Health,
+    Meta
+}
+
+pub(crate) struct Api;
+
+#[OpenApi]
+impl Api {}

backend/src/settings.rs

@@ -0,0 +1,157 @@
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct Settings {
+    pub application: ApplicationSettings,
+    pub debug: bool,
+    pub email: EmailSettings,
+    pub frontend_url: String,
+}
+
+impl Settings {
+    pub fn new() -> Result<Self, config::ConfigError> {
+        let base_path = std::env::current_dir().expect("Failed to determine the current directory");
+        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()
+    }
+}
+
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct ApplicationSettings {
+    pub name: String,
+    pub version: String,
+    pub port: u16,
+    pub host: String,
+    pub base_url: String,
+    pub protocol: String,
+}
+
+#[derive(Debug, PartialEq, Eq, Default)]
+pub enum Environment {
+    #[default]
+    Development,
+    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`"
+            )),
+        }
+    }
+}
+
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct EmailSettings {
+    pub host: String,
+    pub user: String,
+    pub password: String,
+    pub from: String,
+}
+
+#[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);
+    }
+}

backend/src/startup.rs

@@ -0,0 +1,162 @@
+use poem::middleware::{AddDataEndpoint, Cors, CorsEndpoint};
+use poem::{EndpointExt, Route};
+use poem_openapi::OpenApiService;
+
+use crate::{settings::Settings, route::{Api, HealthApi, MetaApi}};
+
+type Server = poem::Server<poem::listener::TcpListener<String>, std::convert::Infallible>;
+pub type App = AddDataEndpoint<CorsEndpoint<Route>, Settings>;
+
+pub struct Application {
+    server: Server,
+    app: poem::Route,
+    host: String,
+    port: u16,
+    settings: Settings,
+}
+
+pub struct RunnableApplication {
+    server: Server,
+    app: App,
+}
+
+impl RunnableApplication {
+    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 {
+        let app = value.app.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, HealthApi, MetaApi),
+            settings.application.clone().name,
+            settings.application.clone().version,
+        );
+        let ui = api_service.swagger_ui();
+        poem::Route::new().nest("/", api_service).nest("/docs", 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)
+    }
+
+    #[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,
+        }
+    }
+
+    #[must_use]
+    pub fn make_app(self) -> RunnableApplication {
+        self.into()
+    }
+
+    #[must_use]
+    pub fn host(&self) -> String {
+        self.host.clone()
+    }
+
+    #[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,
+            email: crate::settings::EmailSettings::default(),
+            frontend_url: "http://localhost:3000".to_string(),
+        }
+    }
+
+    #[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,53 @@
+use tracing_subscriber::layer::SubscriberExt;
+
+#[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)
+}
+
+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;
+    }
+}