Update diagrams

docs/diagrams-src/architecture.puml

@@ -0,0 +1,75 @@
+@startuml architecture
+!theme plain
+skinparam backgroundColor #FFFFFF
+skinparam defaultFontName Arial
+skinparam packageStyle rectangle
+
+title The Biergarten App - Layered Architecture
+
+package "API Layer" #E3F2FD {
+  [API.Core\nASP.NET Core Web API] as API
+  note right of API
+    - Controllers (Auth, User)
+    - Swagger/OpenAPI
+    - Middleware
+    - Health Checks
+  end note
+}
+
+package "Service Layer" #F3E5F5 {
+  [Service.Auth] as AuthSvc
+  [Service.UserManagement] as UserSvc
+  note right of AuthSvc
+    - Business Logic
+    - Validation
+    - Orchestration
+  end note
+}
+
+package "Infrastructure Layer" #FFF3E0 {
+  [Infrastructure.Repository] as Repo
+  [Infrastructure.Jwt] as JWT
+  [Infrastructure.PasswordHashing] as PwdHash
+  [Infrastructure.Email] as Email
+}
+
+package "Domain Layer" #E8F5E9 {
+  [Domain.Entities] as Domain
+  note right of Domain
+    - UserAccount
+    - UserCredential
+    - UserVerification
+  end note
+}
+
+database "SQL Server" {
+  [Stored Procedures] as SP
+  [Tables] as Tables
+}
+
+' Relationships
+API --> AuthSvc
+API --> UserSvc
+
+AuthSvc --> Repo
+AuthSvc --> JWT
+AuthSvc --> PwdHash
+AuthSvc --> Email
+
+UserSvc --> Repo
+
+Repo --> SP
+Repo --> Domain
+SP --> Tables
+
+AuthSvc --> Domain
+UserSvc --> Domain
+
+' Notes
+note left of Repo
+  SQL-first approach
+  All queries via
+  stored procedures
+end note
+
+@enduml

docs/diagrams-src/authentication-flow.puml

@@ -0,0 +1,298 @@
+@startuml authentication-flow
+!theme plain
+skinparam backgroundColor #FFFFFF
+skinparam defaultFontName Arial
+skinparam sequenceMessageAlign center
+skinparam maxMessageSize 200
+
+title User Authentication Flow - Expanded
+
+actor User
+participant "API\nController" as API
+box "Service Layer" #LightBlue
+participant "RegisterService" as RegSvc
+participant "LoginService" as LoginSvc
+participant "TokenService" as TokenSvc
+participant "EmailService" as EmailSvc
+end box
+box "Infrastructure Layer" #LightGreen
+participant "Argon2\nInfrastructure" as Argon2
+participant "JWT\nInfrastructure" as JWT
+participant "Email\nProvider" as SMTP
+participant "Template\nProvider" as Template
+end box
+box "Repository Layer" #LightYellow
+participant "AuthRepository" as AuthRepo
+participant "UserAccount\nRepository" as UserRepo
+end box
+database "SQL Server\nStored Procedures" as DB
+
+== Registration Flow ==
+
+User -> API: POST /api/auth/register\n{username, firstName, lastName,\nemail, dateOfBirth, password}
+activate API
+
+note right of API
+  FluentValidation runs:
+  - Username: 3-64 chars, alphanumeric + [._-]
+  - Email: valid format, max 128 chars
+  - Password: min 8 chars, uppercase,\n    lowercase, number, special char
+  - DateOfBirth: must be 19+ years old
+end note
+
+API -> API: Validate request\n(FluentValidation)
+
+alt Validation fails
+  API -> User: 400 Bad Request\n{errors: {...}}
+else Validation succeeds
+  API -> RegSvc: RegisterAsync(userAccount, password)
+  activate RegSvc
+
+  RegSvc -> AuthRepo: GetUserByUsernameAsync(username)
+  activate AuthRepo
+  AuthRepo -> DB: EXEC usp_GetUserAccountByUsername
+  activate DB
+  DB --> AuthRepo: null (user doesn't exist)
+  deactivate DB
+  deactivate AuthRepo
+
+  RegSvc -> AuthRepo: GetUserByEmailAsync(email)
+  activate AuthRepo
+  AuthRepo -> DB: EXEC usp_GetUserAccountByEmail
+  activate DB
+  DB --> AuthRepo: null (email doesn't exist)
+  deactivate DB
+  deactivate AuthRepo
+
+  alt User/Email already exists
+    RegSvc -> API: throw ConflictException
+    API -> User: 409 Conflict\n"Username or email already exists"
+  else User doesn't exist
+
+    RegSvc -> Argon2: Hash(password)
+    activate Argon2
+    note right of Argon2
+      Argon2id parameters:
+      - Salt: 16 bytes (128-bit)
+      - Memory: 64MB
+      - Iterations: 4
+      - Parallelism: CPU count
+      - Hash output: 32 bytes
+    end note
+    Argon2 -> Argon2: Generate random salt\n(16 bytes)
+    Argon2 -> Argon2: Hash password with\nArgon2id algorithm
+    Argon2 --> RegSvc: "base64(salt):base64(hash)"
+    deactivate Argon2
+
+    RegSvc -> AuthRepo: RegisterUserAsync(\n  username, firstName, lastName,\n  email, dateOfBirth, hash)
+    activate AuthRepo
+
+    AuthRepo -> DB: EXEC USP_RegisterUser
+    activate DB
+    note right of DB
+      Transaction begins:
+      1. INSERT UserAccount
+      2. INSERT UserCredential
+         (with hashed password)
+      Transaction commits
+    end note
+    DB -> DB: BEGIN TRANSACTION
+    DB -> DB: INSERT INTO UserAccount\n(Username, FirstName, LastName,\nEmail, DateOfBirth)
+    DB -> DB: OUTPUT INSERTED.UserAccountID
+    DB -> DB: INSERT INTO UserCredential\n(UserAccountId, Hash)
+    DB -> DB: COMMIT TRANSACTION
+    DB --> AuthRepo: UserAccountId (GUID)
+    deactivate DB
+
+    AuthRepo --> RegSvc: UserAccount entity
+    deactivate AuthRepo
+
+    RegSvc -> TokenSvc: GenerateAccessToken(userAccount)
+    activate TokenSvc
+    TokenSvc -> JWT: GenerateJwt(userId, username, expiry)
+    activate JWT
+    note right of JWT
+      JWT Configuration:
+      - Algorithm: HS256
+      - Expires: 1 hour
+      - Claims:
+        * sub: userId
+        * unique_name: username
+        * jti: unique token ID
+    end note
+    JWT -> JWT: Create JWT with claims
+    JWT -> JWT: Sign with secret key
+    JWT --> TokenSvc: Access Token
+    deactivate JWT
+    TokenSvc --> RegSvc: Access Token
+    deactivate TokenSvc
+
+    RegSvc -> TokenSvc: GenerateRefreshToken(userAccount)
+    activate TokenSvc
+    TokenSvc -> JWT: GenerateJwt(userId, username, expiry)
+    activate JWT
+    note right of JWT
+      Refresh Token:
+      - Expires: 21 days
+      - Same structure as access token
+    end note
+    JWT --> TokenSvc: Refresh Token
+    deactivate JWT
+    TokenSvc --> RegSvc: Refresh Token
+    deactivate TokenSvc
+
+    RegSvc -> EmailSvc: SendRegistrationEmailAsync(\n  createdUser, confirmationToken)
+    activate EmailSvc
+
+    EmailSvc -> Template: RenderUserRegisteredEmailAsync(\n  firstName, confirmationLink)
+    activate Template
+    note right of Template
+      Razor Component:
+      - Header with branding
+      - Welcome message
+      - Confirmation button
+      - Footer
+    end note
+    Template -> Template: Render Razor component\nto HTML
+    Template --> EmailSvc: HTML email content
+    deactivate Template
+
+    EmailSvc -> SMTP: SendAsync(email, subject, body)
+    activate SMTP
+    note right of SMTP
+      SMTP Configuration:
+      - Host: from env (SMTP_HOST)
+      - Port: from env (SMTP_PORT)
+      - TLS: StartTLS
+      - Auth: username/password
+    end note
+    SMTP -> SMTP: Create MIME message
+    SMTP -> SMTP: Connect to SMTP server
+    SMTP -> SMTP: Authenticate
+    SMTP -> SMTP: Send email
+    SMTP -> SMTP: Disconnect
+    SMTP --> EmailSvc: Success / Failure
+    deactivate SMTP
+
+    alt Email sent successfully
+      EmailSvc --> RegSvc: emailSent = true
+    else Email failed
+      EmailSvc --> RegSvc: emailSent = false\n(error suppressed)
+    end
+    deactivate EmailSvc
+
+    RegSvc --> API: RegisterServiceReturn(\n  userAccount, accessToken,\n  refreshToken, emailSent)
+    deactivate RegSvc
+
+    API -> API: Create response body
+    API -> User: 201 Created\n{\n  message: "User registered successfully",\n  payload: {\n    userAccountId, username,\n    accessToken, refreshToken,\n    confirmationEmailSent\n  }\n}
+  end
+end
+deactivate API
+
+== Login Flow ==
+
+User -> API: POST /api/auth/login\n{username, password}
+activate API
+
+API -> API: Validate request\n(FluentValidation)
+
+alt Validation fails
+  API -> User: 400 Bad Request\n{errors: {...}}
+else Validation succeeds
+
+  API -> LoginSvc: LoginAsync(username, password)
+  activate LoginSvc
+
+  LoginSvc -> AuthRepo: GetUserByUsernameAsync(username)
+  activate AuthRepo
+  AuthRepo -> DB: EXEC usp_GetUserAccountByUsername
+  activate DB
+  DB -> DB: SELECT FROM UserAccount\nWHERE Username = @Username
+  DB --> AuthRepo: UserAccount entity
+  deactivate DB
+  deactivate AuthRepo
+
+  alt User not found
+    LoginSvc -> API: throw UnauthorizedException\n"Invalid username or password"
+    API -> User: 401 Unauthorized
+  else User found
+
+    LoginSvc -> AuthRepo: GetActiveCredentialByUserAccountIdAsync(userId)
+    activate AuthRepo
+    AuthRepo -> DB: EXEC USP_GetActiveUserCredentialByUserAccountId
+    activate DB
+    note right of DB
+      SELECT FROM UserCredential
+      WHERE UserAccountId = @UserAccountId
+        AND IsRevoked = 0
+    end note
+    DB --> AuthRepo: UserCredential entity
+    deactivate DB
+    deactivate AuthRepo
+
+    alt No active credential
+      LoginSvc -> API: throw UnauthorizedException
+      API -> User: 401 Unauthorized
+    else Active credential found
+
+      LoginSvc -> Argon2: Verify(password, storedHash)
+      activate Argon2
+      note right of Argon2
+        1. Split stored hash: "salt:hash"
+        2. Extract salt
+        3. Hash provided password\n   with same salt
+        4. Constant-time comparison
+      end note
+      Argon2 -> Argon2: Parse salt from stored hash
+      Argon2 -> Argon2: Hash provided password\nwith extracted salt
+      Argon2 -> Argon2: FixedTimeEquals(\n  computed, stored)
+      Argon2 --> LoginSvc: true/false
+      deactivate Argon2
+
+      alt Password invalid
+        LoginSvc -> API: throw UnauthorizedException
+        API -> User: 401 Unauthorized
+      else Password valid
+
+        LoginSvc -> TokenSvc: GenerateAccessToken(user)
+        activate TokenSvc
+        TokenSvc -> JWT: GenerateJwt(...)
+        activate JWT
+        JWT --> TokenSvc: Access Token
+        deactivate JWT
+        TokenSvc --> LoginSvc: Access Token
+        deactivate TokenSvc
+
+        LoginSvc -> TokenSvc: GenerateRefreshToken(user)
+        activate TokenSvc
+        TokenSvc -> JWT: GenerateJwt(...)
+        activate JWT
+        JWT --> TokenSvc: Refresh Token
+        deactivate JWT
+        TokenSvc --> LoginSvc: Refresh Token
+        deactivate TokenSvc
+
+        LoginSvc --> API: LoginServiceReturn(\n  userAccount, accessToken,\n  refreshToken)
+        deactivate LoginSvc
+
+        API -> User: 200 OK\n{\n  message: "Logged in successfully",\n  payload: {\n    userAccountId, username,\n    accessToken, refreshToken\n  }\n}
+      end
+    end
+  end
+end
+deactivate API
+
+== Error Handling (Global Exception Filter) ==
+
+note over API
+  GlobalExceptionFilter catches:
+  - ValidationException → 400 Bad Request
+  - ConflictException → 409 Conflict
+  - NotFoundException → 404 Not Found
+  - UnauthorizedException → 401 Unauthorized
+  - ForbiddenException → 403 Forbidden
+  - All others → 500 Internal Server Error
+end note
+
+@enduml

docs/diagrams-src/database-schema.puml

@@ -0,0 +1,104 @@
+@startuml database-schema
+!theme plain
+skinparam backgroundColor #FFFFFF
+skinparam defaultFontName Arial
+skinparam linetype ortho
+
+title Key Database Schema - User & Authentication
+
+entity "UserAccount" as User {
+  * UserAccountId: INT <<PK>>
+  --
+  * Username: NVARCHAR(30) <<UNIQUE>>
+  * Email: NVARCHAR(255) <<UNIQUE>>
+  * FirstName: NVARCHAR(50)
+  * LastName: NVARCHAR(50)
+  Bio: NVARCHAR(500)
+  CreatedAt: DATETIME2
+  UpdatedAt: DATETIME2
+  LastLoginAt: DATETIME2
+}
+
+entity "UserCredential" as Cred {
+  * UserCredentialId: INT <<PK>>
+  --
+  * UserAccountId: INT <<FK>>
+  * PasswordHash: VARBINARY(32)
+  * PasswordSalt: VARBINARY(16)
+  CredentialRotatedAt: DATETIME2
+  CredentialExpiresAt: DATETIME2
+  CredentialRevokedAt: DATETIME2
+  * IsActive: BIT
+  CreatedAt: DATETIME2
+}
+
+entity "UserVerification" as Verify {
+  * UserVerificationId: INT <<PK>>
+  --
+  * UserAccountId: INT <<FK>>
+  * IsVerified: BIT
+  VerifiedAt: DATETIME2
+  VerificationToken: NVARCHAR(255)
+  TokenExpiresAt: DATETIME2
+}
+
+entity "UserAvatar" as Avatar {
+  * UserAvatarId: INT <<PK>>
+  --
+  * UserAccountId: INT <<FK>>
+  PhotoId: INT <<FK>>
+  * IsActive: BIT
+  CreatedAt: DATETIME2
+}
+
+entity "UserFollow" as Follow {
+  * UserFollowId: INT <<PK>>
+  --
+  * FollowerUserId: INT <<FK>>
+  * FollowedUserId: INT <<FK>>
+  CreatedAt: DATETIME2
+}
+
+entity "Photo" as Photo {
+  * PhotoId: INT <<PK>>
+  --
+  * Url: NVARCHAR(500)
+  * CloudinaryPublicId: NVARCHAR(255)
+  Width: INT
+  Height: INT
+  Format: NVARCHAR(10)
+  CreatedAt: DATETIME2
+}
+
+' Relationships
+User ||--o{ Cred : "has"
+User ||--o| Verify : "has"
+User ||--o{ Avatar : "has"
+User ||--o{ Follow : "follows"
+User ||--o{ Follow : "followed by"
+Avatar }o--|| Photo : "refers to"
+
+note right of Cred
+  Password hashing:
+  - Algorithm: Argon2id
+  - Memory: 64MB
+  - Iterations: 4
+  - Salt: 128-bit
+  - Hash: 256-bit
+end note
+
+note right of Verify
+  Account verification
+  via email token
+  with expiry
+end note
+
+note bottom of User
+  Core stored procedures:
+  - USP_RegisterUser
+  - USP_GetUserAccountByUsername
+  - USP_RotateUserCredential
+  - USP_UpdateUserAccount
+end note
+
+@enduml

docs/diagrams-src/deployment.puml

@@ -0,0 +1,227 @@
+@startuml deployment
+!theme plain
+skinparam backgroundColor #FFFFFF
+skinparam defaultFontName Arial
+skinparam linetype ortho
+
+title Docker Deployment Architecture
+
+' External systems
+actor Developer
+cloud "Docker Host" as Host
+
+package "Development Environment\n(docker-compose.dev.yaml)" #E3F2FD {
+
+  node "SQL Server\n(mcr.microsoft.com/mssql/server:2022-latest)" as DevDB {
+    database "Biergarten\nDatabase" as DevDBInner {
+      portin "1433"
+    }
+    note right
+      Environment:
+      - ACCEPT_EULA=Y
+      - SA_PASSWORD=***
+      - MSSQL_PID=Developer
+
+      Volumes:
+      - biergarten-dev-data
+    end note
+  }
+
+  node "API Container\n(API.Core)" as DevAPI {
+    component "ASP.NET Core 10" as API1
+    portin "8080:8080 (HTTP)" as DevPort1
+    portin "8081:8081 (HTTPS)" as DevPort2
+
+    note right
+      Environment:
+      - ASPNETCORE_ENVIRONMENT=Development
+      - DB_SERVER=sql-server
+      - DB_NAME=Biergarten
+      - DB_USER/PASSWORD
+      - JWT_SECRET
+      - SMTP_* (10+ variables)
+
+      Health Check:
+      /health endpoint
+    end note
+  }
+
+  node "Migrations\n(run-once)" as DevMig {
+    component "Database.Migrations" as Mig1
+    note bottom
+      Runs: DbUp migrations
+      Environment:
+      - CLEAR_DATABASE=false
+      Depends on: sql-server
+    end note
+  }
+
+  node "Seed\n(run-once)" as DevSeed {
+    component "Database.Seed" as Seed1
+    note bottom
+      Creates:
+      - 100 test users
+      - Location data (US/CA/MX)
+      - test.user account
+      Depends on: migrations
+    end note
+  }
+
+}
+
+package "Test Environment\n(docker-compose.test.yaml)" #FFF3E0 {
+
+  node "SQL Server\n(isolated instance)" as TestDB {
+    database "Biergarten\nTest Database" as TestDBInner {
+      portin "1434"
+    }
+    note right
+      Fresh instance each run
+      CLEAR_DATABASE=true
+
+      Volumes:
+      - biergarten-test-data
+      (ephemeral)
+    end note
+  }
+
+  node "Migrations\n(test)" as TestMig {
+    component "Database.Migrations"
+  }
+
+  node "Seed\n(test)" as TestSeed {
+    component "Database.Seed"
+    note bottom
+      Minimal seed:
+      - test.user only
+      - Essential data
+    end note
+  }
+
+  node "API.Specs\n(Integration Tests)" as Specs {
+    component "Reqnroll + xUnit" as SpecsComp
+    note right
+      Tests:
+      - Registration flow
+      - Login flow
+      - Validation rules
+      - 404 handling
+
+      Uses: TestApiFactory
+      Mocks: Email services
+    end note
+  }
+
+  node "Infrastructure.Repository.Tests\n(Unit Tests)" as RepoTests {
+    component "xUnit + DbMocker" as RepoComp
+    note right
+      Tests:
+      - AuthRepository
+      - UserAccountRepository
+      - SQL command building
+
+      Uses: Mock connections
+      No real database needed
+    end note
+  }
+
+  node "Service.Auth.Tests\n(Unit Tests)" as SvcTests {
+    component "xUnit + Moq" as SvcComp
+    note right
+      Tests:
+      - RegisterService
+      - LoginService
+      - Token generation
+
+      Uses: Mocked dependencies
+      No database or infrastructure
+    end note
+  }
+
+}
+
+folder "test-results/\n(mounted volume)" as Results {
+  file "api-specs/\n  results.trx" as Result1
+  file "repository-tests/\n  results.trx" as Result2
+  file "service-auth-tests/\n  results.trx" as Result3
+
+  note bottom
+    TRX format
+    Readable by:
+    - Visual Studio
+    - Azure DevOps
+    - GitHub Actions
+  end note
+}
+
+' External access
+Developer --> Host : docker compose up
+Host --> DevAPI : http://localhost:8080
+
+' Development dependencies
+DevMig --> DevDB : 1. Run migrations
+DevSeed --> DevDB : 2. Seed data
+DevAPI --> DevDB : 3. Connect & serve
+DevMig .up.> DevDB : depends_on
+DevSeed .up.> DevMig : depends_on
+DevAPI .up.> DevSeed : depends_on
+
+' Test dependencies
+TestMig --> TestDB : 1. Migrate
+TestSeed --> TestDB : 2. Seed
+Specs --> TestDB : 3. Integration test
+RepoTests ..> TestDB : Mock (no connection)
+SvcTests ..> TestDB : Mock (no connection)
+
+TestMig .up.> TestDB : depends_on
+TestSeed .up.> TestMig : depends_on
+Specs .up.> TestSeed : depends_on
+
+' Test results export
+Specs --> Results : Export TRX
+RepoTests --> Results : Export TRX
+SvcTests --> Results : Export TRX
+
+' Network notes
+note bottom of DevDB
+  <b>Dev Network (bridge: biergarten-dev)</b>
+  Internal DNS:
+  - sql-server (resolves to SQL container)
+  - api (resolves to API container)
+end note
+
+note bottom of TestDB
+  <b>Test Network (bridge: biergarten-test)</b>
+  All test components isolated
+end note
+
+' Startup sequence notes
+note top of DevMig
+  Startup Order:
+  1. SQL Server (health check)
+  2. Migrations (run-once)
+  3. Seed (run-once)
+  4. API (long-running)
+end note
+
+note top of Specs
+  Test Execution:
+  All tests run in parallel
+  Results aggregated
+end note
+
+' Production note
+note as ProductionNote
+  <b>Production Deployment (not shown):</b>
+
+  Would include:
+  • Azure SQL Database / AWS RDS
+  • Azure Container Apps / ECS
+  • Azure Key Vault for secrets
+  • Application Insights / CloudWatch
+  • Load balancer
+  • HTTPS termination
+  • CDN for static assets
+end note
+
+@enduml