the-biergarten-app/docs/website/diagrams-md/deployment.md

Docker Deployment Architecture

flowchart TB
    Developer(["Developer"])
    Host[["Docker Host"]]
    Developer -->|docker compose up| Host
    Host -->|http://localhost:8080| DevAPI

    subgraph DEV["Development Environment (docker-compose.dev.yaml)"]
        DevDB[("SQL Server 2022<br/>Biergarten Database<br/>:1433")]
        DevAPI["API Container<br/>ASP.NET Core 10<br/>:8080 HTTP / :8081 HTTPS"]
        DevMig["Migrations (run-once)<br/>Database.Migrations"]
        DevSeed["Seed (run-once)<br/>Database.Seed"]
        DevMailpit["Mailpit<br/>:8025 Web UI / :1025 SMTP"]
    end

    DevMig -->|1. Run migrations| DevDB
    DevSeed -->|2. Seed data| DevDB
    DevAPI -->|3. Connect and serve| DevDB
    DevAPI -.->|4. SMTP_HOST/PORT| DevMailpit
    DevMig -.->|depends_on| DevDB
    DevSeed -.->|depends_on| DevMig
    DevAPI -.->|depends_on| DevSeed

    subgraph TEST["Test Environment (docker-compose.test.yaml)"]
        TestDB[("SQL Server, isolated instance<br/>Biergarten Test Database<br/>:1434")]
        TestMig["Migrations (test)"]
        TestSeed["Seed (test)<br/>minimal: test.user only"]
        Specs["API.Specs<br/>Reqnroll + xUnit<br/>(integration tests)"]
        UnitTests["unit.tests<br/>xUnit + Moq<br/>Features.*.Tests, one container"]
    end

    TestMig -->|1. Migrate| TestDB
    TestSeed -->|2. Seed| TestDB
    Specs -->|3. Integration test| TestDB
    UnitTests -.->|depends_on for startup ordering only, no real connection| TestDB
    TestMig -.->|depends_on| TestDB
    TestSeed -.->|depends_on| TestMig
    Specs -.->|depends_on| TestSeed
    UnitTests -.->|depends_on| TestSeed

    Results[["test-results/ (mounted volume)<br/>api-specs/results.trx<br/>Features.Users.Tests.trx<br/>Features.Breweries.Tests.trx<br/>Features.Emails.Tests.trx"]]
    Specs -->|Export TRX| Results
    UnitTests -->|Export TRX, one per slice| Results

    subgraph PROD["Production Environment (docker-compose.prod.yaml)"]
        ProdDB[("SQL Server 2022<br/>Biergarten Database<br/>no host port published")]
        ProdMig["Migrations (run-once)"]
        ProdAPI["API Container<br/>ASP.NET Core 10<br/>:8080 HTTP / :8081 HTTPS"]
    end

    ProdMig -->|1. Run migrations| ProdDB
    ProdAPI -->|2. Connect and serve| ProdDB
    ProdMig -.->|depends_on| ProdDB
    ProdAPI -.->|"depends_on: sql-server healthy (not migrations/seed)"| ProdDB

    subgraph DBONLY["Database-only Environment (docker-compose.db.yaml)"]
        DbOnlyDB[("SQL Server<br/>:1434")]
        DbOnlyMig["Migrations (run-once)"]
        DbOnlySeed["Seed (run-once)"]
    end

    DbOnlyMig -->|1. Run migrations| DbOnlyDB
    DbOnlySeed -->|2. Seed data| DbOnlyDB
    DbOnlyMig -.->|depends_on| DbOnlyDB
    DbOnlySeed -.->|depends_on| DbOnlyMig

    subgraph MIN["Minimal Environment (docker-compose.min.yaml)"]
        MinDB[("SQL Server<br/>:1433")]
        MinMig["Migrations (run-once)"]
        MinMailpit["Mailpit<br/>:8025 / :1025"]
        MinSeed["Seed (run-once)"]
    end

    MinMig -->|1. Run migrations| MinDB
    MinSeed -->|2. Seed data| MinDB
    MinMig -.->|depends_on| MinDB
    MinSeed -.->|depends_on| MinMig

Notes

• Dev network (biergarten-dev, bridge): internal DNS resolves sql-server and api. Volumes: biergarten-dev-data. Startup order: SQL Server (health check) → migrations (run-once) → seed (run-once) → API (long-running).
• Test network (biergarten-test, bridge): all test components isolated; fresh DB instance each run (CLEAR_DATABASE=true, ephemeral biergarten-test-data volume). All tests run in parallel, results aggregated.
• Prod network (prodnet, bridge): isolated from dev/test networks. Volumes: sqlserverdata-prod, nuget-cache-prod. No seed step in production.
• Database-only environment: same devnet volumes/images as docker-compose.dev.yaml, minus api.core and mailpit — for working against the database without running the API.
• Minimal environment: database + mailpit only, no API container — for frontend development against an API.Core process run outside Docker.
• unit.tests builds Dockerfile.tests, which restores/builds against Core.slnx then runs dotnet test for every Features/*.Tests project in turn (Features.Users.Tests, Features.Breweries.Tests, Features.Emails.Tests), mocking each handler's repository/service dependencies with Moq — no real database needed.
• .trx results are readable by Visual Studio, Azure DevOps, and GitHub Actions.