@opengroundplan/core 0.1.1

package/templates/layers/db-mongo/files/internal/db/mongodb/config.go

@@ -0,0 +1,105 @@
+package mongodb
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"time"
+)
+
+// The only place a Mongo literal appears; every tunable is overridable from the environment.
+const (
+	defaultURI                    = "mongodb://localhost:{{ mongoPort }}/?directConnection=true"
+	defaultDatabase               = "{{ solutionName | snake }}"
+	defaultAppName                = "{{ solutionName | kebab }}"
+	defaultMaxPoolSize            = 20
+	defaultMinPoolSize            = 0
+	defaultServerSelectionTimeout = 5 * time.Second
+	defaultConnectTimeout         = 10 * time.Second
+	defaultRetryWrites            = true
+)
+
+type Config struct {
+	URI                    string
+	Database               string
+	AppName                string
+	MaxPoolSize            uint64
+	MinPoolSize            uint64
+	ServerSelectionTimeout time.Duration
+	ConnectTimeout         time.Duration
+	RetryWrites            bool
+}
+
+// LoadConfig fails fast: a malformed limit must not reach the connection pool.
+func LoadConfig() (Config, error) {
+	maxPool, err := envUint("MONGO_MAX_POOL_SIZE", defaultMaxPoolSize)
+	if err != nil {
+		return Config{}, err
+	}
+	minPool, err := envUint("MONGO_MIN_POOL_SIZE", defaultMinPoolSize)
+	if err != nil {
+		return Config{}, err
+	}
+	selectionTimeout, err := envMillis("MONGO_SERVER_SELECTION_TIMEOUT_MS", defaultServerSelectionTimeout)
+	if err != nil {
+		return Config{}, err
+	}
+	connectTimeout, err := envMillis("MONGO_CONNECT_TIMEOUT_MS", defaultConnectTimeout)
+	if err != nil {
+		return Config{}, err
+	}
+
+	return Config{
+		URI:                    envString("MONGO_URI", defaultURI),
+		Database:               envString("MONGO_DATABASE", defaultDatabase),
+		AppName:                envString("MONGO_APP_NAME", defaultAppName),
+		MaxPoolSize:            maxPool,
+		MinPoolSize:            minPool,
+		ServerSelectionTimeout: selectionTimeout,
+		ConnectTimeout:         connectTimeout,
+		RetryWrites:            envBool("MONGO_RETRY_WRITES", defaultRetryWrites),
+	}, nil
+}
+
+func envString(name, fallback string) string {
+	if raw := os.Getenv(name); raw != "" {
+		return raw
+	}
+	return fallback
+}
+
+func envUint(name string, fallback uint64) (uint64, error) {
+	raw := os.Getenv(name)
+	if raw == "" {
+		return fallback, nil
+	}
+	value, err := strconv.ParseUint(raw, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("%s must be a non-negative integer: %w", name, err)
+	}
+	return value, nil
+}
+
+func envMillis(name string, fallback time.Duration) (time.Duration, error) {
+	raw := os.Getenv(name)
+	if raw == "" {
+		return fallback, nil
+	}
+	value, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("%s must be an integer number of milliseconds: %w", name, err)
+	}
+	return time.Duration(value) * time.Millisecond, nil
+}
+
+func envBool(name string, fallback bool) bool {
+	raw := os.Getenv(name)
+	if raw == "" {
+		return fallback
+	}
+	value, err := strconv.ParseBool(raw)
+	if err != nil {
+		return fallback
+	}
+	return value
+}

package/templates/layers/db-mongo/files/internal/db/mongodb/indexes.go

@@ -0,0 +1,42 @@
+package mongodb
+
+import (
+	"context"
+
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type IndexDefinition struct {
+	Collection string
+	Model      mongo.IndexModel
+}
+
+// Declare indexes here so schema intent is reviewable in git.
+var IndexDefinitions = []IndexDefinition{
+	// {
+	// 	Collection: "users",
+	// 	Model: mongo.IndexModel{
+	// 		Keys:    bson.D{{Key: "email", Value: 1}},
+	// 		Options: options.Index().SetUnique(true).SetName("users_email_unique"),
+	// 	},
+	// },
+}
+
+// EnsureIndexes is idempotent — safe on every boot and in tests.
+func EnsureIndexes(ctx context.Context, cfg Config, definitions []IndexDefinition) error {
+	if definitions == nil {
+		definitions = IndexDefinitions
+	}
+
+	db, err := Database(cfg)
+	if err != nil {
+		return err
+	}
+
+	for _, definition := range definitions {
+		if _, err := db.Collection(definition.Collection).Indexes().CreateOne(ctx, definition.Model); err != nil {
+			return err
+		}
+	}
+	return nil
+}

package/templates/layers/db-mongo/files/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "mongodb": "^7.5.0"
+  }
+}

package/templates/layers/db-mongo/files/pyproject.toml

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["pymongo>=4.17.0"]

package/templates/layers/db-mongo/files/requirements-mongo.txt

@@ -0,0 +1,2 @@
+# Install with: pip install -r requirements-mongo.txt (or add the pin to pyproject.toml)
+pymongo==4.17.0

package/templates/layers/db-mongo/files/src/__solutionName.dot__.Infrastructure.Mongo/MongoContext.cs

@@ -0,0 +1,21 @@
+using Microsoft.Extensions.Options;
+using MongoDB.Driver;
+
+namespace {{ solutionName | dot }}.Infrastructure.Mongo;
+
+/// <summary>Single entry point to the configured database; inject this, never IMongoClient.</summary>
+public sealed class MongoContext
+{
+    public MongoContext(IMongoClient client, IOptions<MongoOptions> options)
+    {
+        Client = client;
+        Database = client.GetDatabase(options.Value.Database);
+    }
+
+    public IMongoClient Client { get; }
+
+    public IMongoDatabase Database { get; }
+
+    public IMongoCollection<TDocument> Collection<TDocument>(string name) =>
+        Database.GetCollection<TDocument>(name);
+}

package/templates/layers/db-mongo/files/src/__solutionName.dot__.Infrastructure.Mongo/MongoHealthCheck.cs

@@ -0,0 +1,28 @@
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using MongoDB.Bson;
+
+namespace {{ solutionName | dot }}.Infrastructure.Mongo;
+
+public sealed class MongoHealthCheck : IHealthCheck
+{
+    private static readonly BsonDocument PingCommand = new("ping", 1);
+
+    private readonly MongoContext _context;
+
+    public MongoHealthCheck(MongoContext context) => _context = context;
+
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await _context.Database.RunCommandAsync<BsonDocument>(PingCommand, cancellationToken: cancellationToken);
+            return HealthCheckResult.Healthy();
+        }
+        catch (Exception exception)
+        {
+            return HealthCheckResult.Unhealthy("MongoDB ping failed.", exception);
+        }
+    }
+}

package/templates/layers/db-mongo/files/src/__solutionName.dot__.Infrastructure.Mongo/MongoIndexes.cs

@@ -0,0 +1,25 @@
+using MongoDB.Bson;
+using MongoDB.Driver;
+
+namespace {{ solutionName | dot }}.Infrastructure.Mongo;
+
+/// <summary>Declare indexes here so schema intent is reviewable in git.</summary>
+public static class MongoIndexes
+{
+    private static readonly IReadOnlyList<(string Collection, CreateIndexModel<BsonDocument> Model)> Definitions =
+    [
+        // ("users", new CreateIndexModel<BsonDocument>(
+        //     Builders<BsonDocument>.IndexKeys.Ascending("email"),
+        //     new CreateIndexOptions { Unique = true, Name = "users_email_unique" })),
+    ];
+
+    /// <summary>Idempotent — safe to call on every start-up.</summary>
+    public static async Task EnsureAsync(MongoContext context, CancellationToken cancellationToken = default)
+    {
+        foreach (var (collection, model) in Definitions)
+        {
+            await context.Collection<BsonDocument>(collection).Indexes
+                .CreateOneAsync(model, cancellationToken: cancellationToken);
+        }
+    }
+}

package/templates/layers/db-mongo/files/src/__solutionName.dot__.Infrastructure.Mongo/MongoOptions.cs

@@ -0,0 +1,23 @@
+namespace {{ solutionName | dot }}.Infrastructure.Mongo;
+
+/// <summary>Bound from the "Mongo" configuration section; the defaults here are the only Mongo literals in the app.</summary>
+public sealed class MongoOptions
+{
+    public const string SectionName = "Mongo";
+
+    public string Uri { get; set; } = "mongodb://localhost:{{ mongoPort }}/?directConnection=true";
+
+    public string Database { get; set; } = "{{ solutionName | snake }}";
+
+    public string AppName { get; set; } = "{{ solutionName | kebab }}";
+
+    public int MaxPoolSize { get; set; } = 20;
+
+    public int MinPoolSize { get; set; }
+
+    public int ServerSelectionTimeoutMs { get; set; } = 5_000;
+
+    public int ConnectTimeoutMs { get; set; } = 10_000;
+
+    public bool RetryWrites { get; set; } = true;
+}

package/templates/layers/db-mongo/files/src/__solutionName.dot__.Infrastructure.Mongo/MongoServiceCollectionExtensions.cs

@@ -0,0 +1,31 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using MongoDB.Driver;
+
+namespace {{ solutionName | dot }}.Infrastructure.Mongo;
+
+public static class MongoServiceCollectionExtensions
+{
+    /// <summary>Registers one pooled client for the whole process — MongoClient is thread-safe by design.</summary>
+    public static IServiceCollection AddMongo(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.Configure<MongoOptions>(configuration.GetSection(MongoOptions.SectionName));
+
+        services.AddSingleton<IMongoClient>(provider =>
+        {
+            var options = provider.GetRequiredService<IOptions<MongoOptions>>().Value;
+            var settings = MongoClientSettings.FromConnectionString(options.Uri);
+            settings.ApplicationName = options.AppName;
+            settings.MaxConnectionPoolSize = options.MaxPoolSize;
+            settings.MinConnectionPoolSize = options.MinPoolSize;
+            settings.ServerSelectionTimeout = TimeSpan.FromMilliseconds(options.ServerSelectionTimeoutMs);
+            settings.ConnectTimeout = TimeSpan.FromMilliseconds(options.ConnectTimeoutMs);
+            settings.RetryWrites = options.RetryWrites;
+            return new MongoClient(settings);
+        });
+
+        services.AddSingleton<MongoContext>();
+        return services;
+    }
+}

package/templates/layers/db-mongo/files/src/__solutionName.dot__.Infrastructure.Mongo/__solutionName.dot__.Infrastructure.Mongo.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Infrastructure.Mongo</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Infrastructure.Mongo</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="MongoDB.Driver" />
+    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
+    <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
+  </ItemGroup>
+
+</Project>

package/templates/layers/db-mongo/files/src/__solutionName.snake__/db/mongo/client.py

@@ -0,0 +1,48 @@
+"""Process-wide async Mongo client. PyMongo ships native asyncio, so Motor is not needed."""
+
+from typing import Any, Dict, Optional
+
+from pymongo import AsyncMongoClient
+from pymongo.asynchronous.database import AsyncDatabase
+
+from .config import MongoConfig, resolve
+
+_client: Optional[AsyncMongoClient] = None
+
+
+def get_client(config: Optional[MongoConfig] = None) -> AsyncMongoClient:
+    """One pool per process; the driver connects lazily on first use."""
+    global _client
+    if _client is None:
+        settings = resolve(config)
+        _client = AsyncMongoClient(
+            settings.uri,
+            appname=settings.app_name,
+            maxPoolSize=settings.max_pool_size,
+            minPoolSize=settings.min_pool_size,
+            serverSelectionTimeoutMS=settings.server_selection_timeout_ms,
+            connectTimeoutMS=settings.connect_timeout_ms,
+            retryWrites=settings.retry_writes,
+        )
+    return _client
+
+
+def get_database(config: Optional[MongoConfig] = None) -> AsyncDatabase[Dict[str, Any]]:
+    settings = resolve(config)
+    return get_client(settings)[settings.database]
+
+
+async def ping(config: Optional[MongoConfig] = None) -> bool:
+    try:
+        await get_client(config).admin.command("ping")
+        return True
+    except Exception:  # health checks report, they never raise
+        return False
+
+
+async def close() -> None:
+    """Call from your shutdown hook — an open pool holds the event loop."""
+    global _client
+    if _client is not None:
+        await _client.close()
+        _client = None

package/templates/layers/db-mongo/files/src/__solutionName.snake__/db/mongo/config.py

@@ -0,0 +1,66 @@
+"""Mongo settings resolved from the environment, with one typed default table."""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+_DEFAULT_URI = "mongodb://localhost:{{ mongoPort }}/?directConnection=true"
+_DEFAULT_DATABASE = "{{ solutionName | snake }}"
+_DEFAULT_APP_NAME = "{{ solutionName | kebab }}"
+_DEFAULT_MAX_POOL_SIZE = 20
+_DEFAULT_MIN_POOL_SIZE = 0
+_DEFAULT_SERVER_SELECTION_TIMEOUT_MS = 5000
+_DEFAULT_CONNECT_TIMEOUT_MS = 10000
+_DEFAULT_RETRY_WRITES = True
+
+_TRUTHY = {"1", "true", "yes"}
+
+
+def _str(name: str, fallback: str) -> str:
+    return os.environ.get(name) or fallback
+
+
+def _int(name: str, fallback: int) -> int:
+    raw = os.environ.get(name)
+    if not raw:
+        return fallback
+    try:
+        return int(raw)
+    except ValueError as error:  # fail at start-up, not on the first query
+        raise ValueError(f"{name} must be an integer, got {raw!r}") from error
+
+
+def _bool(name: str, fallback: bool) -> bool:
+    raw = os.environ.get(name)
+    return fallback if not raw else raw.lower() in _TRUTHY
+
+
+@dataclass(frozen=True)
+class MongoConfig:
+    uri: str
+    database: str
+    app_name: str
+    max_pool_size: int
+    min_pool_size: int
+    server_selection_timeout_ms: int
+    connect_timeout_ms: int
+    retry_writes: bool
+
+    @classmethod
+    def from_env(cls) -> "MongoConfig":
+        return cls(
+            uri=_str("MONGO_URI", _DEFAULT_URI),
+            database=_str("MONGO_DATABASE", _DEFAULT_DATABASE),
+            app_name=_str("MONGO_APP_NAME", _DEFAULT_APP_NAME),
+            max_pool_size=_int("MONGO_MAX_POOL_SIZE", _DEFAULT_MAX_POOL_SIZE),
+            min_pool_size=_int("MONGO_MIN_POOL_SIZE", _DEFAULT_MIN_POOL_SIZE),
+            server_selection_timeout_ms=_int(
+                "MONGO_SERVER_SELECTION_TIMEOUT_MS", _DEFAULT_SERVER_SELECTION_TIMEOUT_MS
+            ),
+            connect_timeout_ms=_int("MONGO_CONNECT_TIMEOUT_MS", _DEFAULT_CONNECT_TIMEOUT_MS),
+            retry_writes=_bool("MONGO_RETRY_WRITES", _DEFAULT_RETRY_WRITES),
+        )
+
+
+def resolve(config: Optional[MongoConfig]) -> MongoConfig:
+    return config if config is not None else MongoConfig.from_env()

package/templates/layers/db-mongo/files/src/__solutionName.snake__/db/mongo/indexes.py

@@ -0,0 +1,29 @@
+"""Index declarations. Keeping them in git is the difference between a schema and a rumour."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+from .client import get_database
+from .config import MongoConfig
+
+
+@dataclass(frozen=True)
+class IndexDefinition:
+    collection: str
+    keys: List[Tuple[str, int]]
+    options: Dict[str, Any] = field(default_factory=dict)
+
+
+INDEX_DEFINITIONS: List[IndexDefinition] = [
+    # IndexDefinition("users", [("email", 1)], {"unique": True, "name": "users_email_unique"}),
+]
+
+
+async def ensure_indexes(
+    definitions: Optional[List[IndexDefinition]] = None,
+    config: Optional[MongoConfig] = None,
+) -> None:
+    """Idempotent — safe on every boot and in test setup."""
+    database = get_database(config)
+    for definition in definitions if definitions is not None else INDEX_DEFINITIONS:
+        await database[definition.collection].create_index(definition.keys, **definition.options)

package/templates/layers/db-mongo/files/src/db/mongo/client.rs

@@ -0,0 +1,37 @@
+use mongodb::bson::doc;
+use mongodb::options::ClientOptions;
+use mongodb::{Client, Database};
+use tokio::sync::OnceCell;
+
+use super::config::MongoConfig;
+
+static CLIENT: OnceCell<Client> = OnceCell::const_new();
+
+/// One pool per process; the driver connects lazily and reconnects on its own.
+pub async fn client() -> mongodb::error::Result<&'static Client> {
+    CLIENT
+        .get_or_try_init(|| async {
+            let config = MongoConfig::from_env();
+            let mut options = ClientOptions::parse(&config.uri).await?;
+            options.app_name = Some(config.app_name);
+            options.max_pool_size = Some(config.max_pool_size);
+            options.min_pool_size = Some(config.min_pool_size);
+            options.server_selection_timeout = Some(config.server_selection_timeout);
+            options.connect_timeout = Some(config.connect_timeout);
+            options.retry_writes = Some(config.retry_writes);
+            Client::with_options(options)
+        })
+        .await
+}
+
+pub async fn database() -> mongodb::error::Result<Database> {
+    let config = MongoConfig::from_env();
+    Ok(client().await?.database(&config.database))
+}
+
+pub async fn ping() -> bool {
+    match database().await {
+        Ok(db) => db.run_command(doc! { "ping": 1 }).await.is_ok(),
+        Err(_) => false,
+    }
+}

package/templates/layers/db-mongo/files/src/db/mongo/client.ts

@@ -0,0 +1,51 @@
+import { MongoClient, type Db } from 'mongodb';
+import { loadMongoConfig, type MongoConfig } from './config.js';
+
+let client: MongoClient | undefined;
+let connecting: Promise<MongoClient> | undefined;
+
+/** One pool per process; concurrent callers share the same in-flight connect. */
+export async function getMongoClient(config: MongoConfig = loadMongoConfig()): Promise<MongoClient> {
+  if (client) return client;
+
+  if (!connecting) {
+    connecting = new MongoClient(config.uri, {
+      appName: config.appName,
+      maxPoolSize: config.maxPoolSize,
+      minPoolSize: config.minPoolSize,
+      serverSelectionTimeoutMS: config.serverSelectionTimeoutMs,
+      connectTimeoutMS: config.connectTimeoutMs,
+      retryWrites: config.retryWrites,
+    })
+      .connect()
+      // Clear the cached promise so a transient failure does not poison every later call.
+      .catch((error: unknown) => {
+        connecting = undefined;
+        throw error;
+      });
+  }
+
+  client = await connecting;
+  return client;
+}
+
+export async function getDb(config: MongoConfig = loadMongoConfig()): Promise<Db> {
+  return (await getMongoClient(config)).db(config.database);
+}
+
+export async function pingMongo(config: MongoConfig = loadMongoConfig()): Promise<boolean> {
+  try {
+    await (await getDb(config)).command({ ping: 1 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Call from your shutdown hook — an open pool keeps the process alive. */
+export async function closeMongo(): Promise<void> {
+  const open = client;
+  client = undefined;
+  connecting = undefined;
+  await open?.close();
+}

package/templates/layers/db-mongo/files/src/db/mongo/config.rs

@@ -0,0 +1,68 @@
+use std::env;
+use std::time::Duration;
+
+/// The only place a Mongo literal appears; every field is overridable from the environment.
+const DEFAULT_URI: &str = "mongodb://localhost:{{ mongoPort }}/?directConnection=true";
+const DEFAULT_DATABASE: &str = "{{ solutionName | snake }}";
+const DEFAULT_APP_NAME: &str = "{{ solutionName | kebab }}";
+const DEFAULT_MAX_POOL_SIZE: u32 = 20;
+const DEFAULT_MIN_POOL_SIZE: u32 = 0;
+const DEFAULT_SERVER_SELECTION_TIMEOUT_MS: u64 = 5_000;
+const DEFAULT_CONNECT_TIMEOUT_MS: u64 = 10_000;
+const DEFAULT_RETRY_WRITES: bool = true;
+
+#[derive(Debug, Clone)]
+pub struct MongoConfig {
+    pub uri: String,
+    pub database: String,
+    pub app_name: String,
+    pub max_pool_size: u32,
+    pub min_pool_size: u32,
+    pub server_selection_timeout: Duration,
+    pub connect_timeout: Duration,
+    pub retry_writes: bool,
+}
+
+impl MongoConfig {
+    /// Panics on a malformed value — a bad pool size must not reach the driver.
+    pub fn from_env() -> Self {
+        Self {
+            uri: env_string("MONGO_URI", DEFAULT_URI),
+            database: env_string("MONGO_DATABASE", DEFAULT_DATABASE),
+            app_name: env_string("MONGO_APP_NAME", DEFAULT_APP_NAME),
+            max_pool_size: env_parse("MONGO_MAX_POOL_SIZE", DEFAULT_MAX_POOL_SIZE),
+            min_pool_size: env_parse("MONGO_MIN_POOL_SIZE", DEFAULT_MIN_POOL_SIZE),
+            server_selection_timeout: Duration::from_millis(env_parse(
+                "MONGO_SERVER_SELECTION_TIMEOUT_MS",
+                DEFAULT_SERVER_SELECTION_TIMEOUT_MS,
+            )),
+            connect_timeout: Duration::from_millis(env_parse(
+                "MONGO_CONNECT_TIMEOUT_MS",
+                DEFAULT_CONNECT_TIMEOUT_MS,
+            )),
+            retry_writes: env_parse("MONGO_RETRY_WRITES", DEFAULT_RETRY_WRITES),
+        }
+    }
+}
+
+impl Default for MongoConfig {
+    fn default() -> Self {
+        Self::from_env()
+    }
+}
+
+fn env_string(name: &str, fallback: &str) -> String {
+    match env::var(name) {
+        Ok(value) if !value.is_empty() => value,
+        _ => fallback.to_owned(),
+    }
+}
+
+fn env_parse<T: std::str::FromStr>(name: &str, fallback: T) -> T {
+    match env::var(name) {
+        Ok(value) if !value.is_empty() => value
+            .parse()
+            .unwrap_or_else(|_| panic!("{name} has an invalid value: {value}")),
+        _ => fallback,
+    }
+}

package/templates/layers/db-mongo/files/src/db/mongo/config.ts

@@ -0,0 +1,58 @@
+export interface MongoConfig {
+  uri: string;
+  database: string;
+  appName: string;
+  maxPoolSize: number;
+  minPoolSize: number;
+  serverSelectionTimeoutMs: number;
+  connectTimeoutMs: number;
+  retryWrites: boolean;
+}
+
+/** The only place a Mongo literal is allowed to appear; everything else reads this config. */
+const defaults: MongoConfig = {
+  uri: 'mongodb://localhost:{{ mongoPort }}/?directConnection=true',
+  database: '{{ solutionName | snake }}',
+  appName: '{{ solutionName | kebab }}',
+  maxPoolSize: 20,
+  minPoolSize: 0,
+  serverSelectionTimeoutMs: 5_000,
+  connectTimeoutMs: 10_000,
+  retryWrites: true,
+};
+
+type Env = Record<string, string | undefined>;
+
+function str(raw: string | undefined, fallback: string): string {
+  return raw === undefined || raw === '' ? fallback : raw;
+}
+
+function num(name: string, raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw === '') return fallback;
+  const parsed = Number(raw);
+  // Fail at startup rather than silently pooling with NaN.
+  if (!Number.isFinite(parsed)) throw new Error(`${name} must be numeric, got "${raw}"`);
+  return parsed;
+}
+
+function bool(raw: string | undefined, fallback: boolean): boolean {
+  if (raw === undefined || raw === '') return fallback;
+  return ['1', 'true', 'yes'].includes(raw.toLowerCase());
+}
+
+export function loadMongoConfig(env: Env = process.env as Env): MongoConfig {
+  return {
+    uri: str(env.MONGO_URI, defaults.uri),
+    database: str(env.MONGO_DATABASE, defaults.database),
+    appName: str(env.MONGO_APP_NAME, defaults.appName),
+    maxPoolSize: num('MONGO_MAX_POOL_SIZE', env.MONGO_MAX_POOL_SIZE, defaults.maxPoolSize),
+    minPoolSize: num('MONGO_MIN_POOL_SIZE', env.MONGO_MIN_POOL_SIZE, defaults.minPoolSize),
+    serverSelectionTimeoutMs: num(
+      'MONGO_SERVER_SELECTION_TIMEOUT_MS',
+      env.MONGO_SERVER_SELECTION_TIMEOUT_MS,
+      defaults.serverSelectionTimeoutMs,
+    ),
+    connectTimeoutMs: num('MONGO_CONNECT_TIMEOUT_MS', env.MONGO_CONNECT_TIMEOUT_MS, defaults.connectTimeoutMs),
+    retryWrites: bool(env.MONGO_RETRY_WRITES, defaults.retryWrites),
+  };
+}