feat(backend): restructure API into layers with OpenAPI, versioning and error handling

Split the backend into API host, Domain, Application and Infrastructure projects. Add Swagger/OpenAPI per API version, Asp.Versioning (query/header), ProblemDetails with a global exception handler and SurrealQL migrations applied at startup (namespace/database ensured). Infrastructure owns the SurrealDB client, settings and DI.

backend/Program.cs

@@ -1,61 +1,74 @@
-using TarninaHub.Services;
-using TarninaHub.Settings;
+using Asp.Versioning;
+using Asp.Versioning.ApiExplorer;
+using Microsoft.Extensions.Options;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using TarninaHub.Application.Abstractions;
+using TarninaHub.Configuration;
+using TarninaHub.Errors;
+using TarninaHub.Infrastructure;
 
 var builder = WebApplication.CreateBuilder(args);
 
-var surrealSettings = builder.Configuration.GetSection("SurrealDb").Get<SurrealDbSettings>()
-    ?? new SurrealDbSettings();
-
-builder.Services.Configure<SurrealDbSettings>(builder.Configuration.GetSection("SurrealDb"));
-
-// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
-builder.Services.AddOpenApi();
+// Layered infrastructure: SurrealDB client, settings and persistence services.
+builder.Services.AddInfrastructure(builder.Configuration);
 
 builder.Services.AddControllers();
 
-builder.Services.AddSingleton<IStorageService, StorageService>();
+// Uniform error responses (RFC 7807) and a global exception handler.
+builder.Services.AddProblemDetails();
+builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
 
-var surrealOptions = new SurrealDbOptions
-{
-    Endpoint = BuildEndpoint(surrealSettings),
-    Namespace = surrealSettings.Namespace,
-    Database = surrealSettings.Database,
-};
+// API versioning: `?api-version=1.0` or header `X-Api-Version`; default 1.0.
+builder.Services
+    .AddApiVersioning(options =>
+    {
+        options.DefaultApiVersion = new ApiVersion(1, 0);
+        options.AssumeDefaultVersionWhenUnspecified = true;
+        options.ApiVersionReader = ApiVersionReader.Combine(
+            new QueryStringApiVersionReader("api-version"),
+            new HeaderApiVersionReader("X-Api-Version"));
+        options.ReportApiVersions = true;
+    })
+    .AddMvc()
+    .AddApiExplorer(options =>
+    {
+        options.GroupNameFormat = "'v'VVV";
+        options.SubstituteApiVersionInUrl = true;
+    });
 
-if (string.IsNullOrWhiteSpace(surrealSettings.RemoteUrl))
-{
-    // Embedded RocksDB, persisted next to the running app (./data), never in memory.
-    var dataDirectory = Path.Combine(AppContext.BaseDirectory, surrealSettings.DataDirectory);
-    Directory.CreateDirectory(dataDirectory);
-
-    builder.Services
-        .AddSurreal(surrealOptions, ServiceLifetime.Singleton)
-        .AddRocksDbProvider();
-}
-else
-{
-    // Remote SurrealDB server on its own dedicated port (used for sync with the frontend).
-    surrealOptions.Username = surrealSettings.Username;
-    surrealOptions.Password = surrealSettings.Password;
-
-    builder.Services.AddSurreal(surrealOptions, ServiceLifetime.Singleton);
-}
+// OpenAPI document + Swagger UI (Swashbuckle), one document per API version.
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
+builder.Services.AddSwaggerGen();
 
 var app = builder.Build();
 
 using (var scope = app.Services.CreateScope())
 {
+    var migrationRunner = scope.ServiceProvider.GetRequiredService<IMigrationRunner>();
     var storageService = scope.ServiceProvider.GetRequiredService<IStorageService>();
 
+    await migrationRunner.ApplyAsync(CancellationToken.None);
     await storageService.InitializeAsync(CancellationToken.None);
 }
 
-// Configure the HTTP request pipeline.
-if (app.Environment.IsDevelopment())
+app.UseExceptionHandler();
+app.UseStatusCodePages();
+
+app.UseSwagger();
+app.UseSwaggerUI(options =>
 {
-    app.MapOpenApi();
-}
-else
+    var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
+
+    foreach (var description in provider.ApiVersionDescriptions)
+    {
+        options.SwaggerEndpoint(
+            $"/swagger/{description.GroupName}/swagger.json",
+            $"TarninaHub API {description.GroupName.ToUpperInvariant()}");
+    }
+});
+
+if (!app.Environment.IsDevelopment())
 {
     app.UseHttpsRedirection();
 }
@@ -68,15 +81,3 @@ app.MapControllers();
 app.MapFallbackToFile("index.html");
 
 app.Run();
-
-static string BuildEndpoint(SurrealDbSettings settings)
-{
-    if (!string.IsNullOrWhiteSpace(settings.RemoteUrl))
-    {
-        return settings.RemoteUrl;
-    }
-
-    var dataDirectory = Path.Combine(AppContext.BaseDirectory, settings.DataDirectory);
-
-    return $"rocksdb://{dataDirectory.Replace('\\', '/')}";
-}