# davidfowl/todoapp architecture

> Architecture diagram of the GitHub repository davidfowl/todoapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davidfowl/todoapp
- Repository: https://github.com/davidfowl/todoapp

## Overview

##### Project type and purpose
- This is a full-stack ASP.NET Core “Todo” application:
– Front end: Blazor WebAssembly hosted by an ASP.NET Core server (Todo.Web)
– Back end: Minimal-API REST service with EF Core + SQLite (Todo.Api)
– AppHost: orchestrator that boots both front-end host and API via .NET Aspire (TodoApp.AppHost)
- It demonstrates authentication (cookie + bearer + external/OIDC), YARP proxying, rate limiting, OpenAPI/Swagger, EF migrations, OpenTelemetry, and integration testing.

##### File structure
- Top-level solution (`TodoApp.sln`) includes:
- Todo.Web
– Client (WASM UI components, shared DTOs, static assets)
– Server (hosts the WASM app, implements cookie auth, forwards API calls via YARP, OpenTelemetry, rate limiting)
- Todo.Api
– Minimal API endpoints (UsersApi, TodoApi), EF Core DbContext, migrations, OpenAPI setup, custom filters (validation), authorization handlers
- TodoApp.AppHost
– Single executable entry point that configures and runs both Todo.Web/Server and Todo.Api
- TodoApp.ServiceDefaults
– Shared extension methods to DRY up service registrations
- Todo.Web.Shared
– Shared models/DTOs between client and server
- Todo.Api.Tests
– Integration tests for API (in-memory database, token service mocks)
- Notice configuration files (`appsettings.json`, launchSettings), CI workflow, devcontainers, and global.json/nuget.config.

##### Key architecture insights from README
- Hosted Blazor WASM + minimal REST API
- YARP’s IHttpForwarder proxies front-end server calls to API
- ASP.NET Core Identity (cookie + bearer + external providers)
- OpenTelemetry instrumentation
- SQLite via EF Core
- Integration tests exercising the full API

##### Details to capture
– The multi-host setup via .NET Aspire (AppHost)
– The dual-authentication mechanisms (cookie for UI, bearer for API)
– Proxying by YARP (path‐based routing)
– External identity provider integrations
– OpenTelemetry telemetry flows
– EF Core migrations & SQLite as the persistence layer

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "AppHost (.NET Aspire)"
        direction TB

        subgraph "Frontend - Todo.Web Server"
            direction TB
            UI["Blazor WASM Client"]:::frontend
            SharedDTOs["Shared Models/DTOs"]:::frontend
            AuthExtensions["Cookie & External Auth Extensions"]:::frontend
            AuthAPI["AuthApi"]:::frontend
            AuthClient["AuthClient"]:::frontend
            YARP["YARP Proxy Module"]:::frontend

            UI -->|serves static UI & calls API| AuthAPI
            AuthAPI -->|uses| AuthExtensions
            AuthAPI -->|forwards via| YARP
            AuthClient -->|invoked by UI| AuthAPI
            SharedDTOs --> UI
            SharedDTOs --> AuthAPI
        end

        subgraph "Backend - Todo.Api Service"
            direction TB
            Middleware["Middleware Pipeline"]:::backend
            TodosAPI["TodoApi Endpoints"]:::backend
            UsersAPI["UsersApi Endpoints"]:::backend
            DbContext["EF Core DbContext & SQLite"]:::backend
            OpenAPI["OpenAPI/Swagger Config"]:::backend
            RateLimit["Rate Limiting Extensions"]:::backend
            Validation["Validation Filter"]:::backend
            AuthHandlers["Authorization Handlers"]:::backend

            TodosAPI -->|depends on| Middleware
            UsersAPI -->|depends on| Middleware
            Middleware -->|auth, rate-limit, validation| AuthHandlers
            Middleware -->|rate limiting| RateLimit
            Middleware -->|validation| Validation
            Middleware -->|swagger| OpenAPI
            DbContext -->|persistence| TodosAPI
            DbContext -->|persistence| UsersAPI
        end

        UI -->|API calls via proxy| YARP
        YARP -->|forwards to| TodosAPI
        YARP -->|forwards to| UsersAPI

        subgraph "External Identity Providers"
            direction TB
            GitHub["GitHub"]:::external
            Google["Google"]:::external
            Microsoft["Microsoft"]:::external
            Auth0["Auth0"]:::external
        end

        GitHub -->|OIDC flow| AuthExtensions
        Google -->|OIDC flow| AuthExtensions
        Microsoft -->|OIDC flow| AuthExtensions
        Auth0 -->|OIDC flow| AuthExtensions

        GitHub -->|token validation| AuthHandlers
        Google -->|token validation| AuthHandlers
        Microsoft -->|token validation| AuthHandlers
        Auth0 -->|token validation| AuthHandlers

        subgraph "OpenTelemetry"
            Collector["OTel Collector/Dashboard"]:::infra
        end

        UI -->|traces/logs| Collector
        AuthAPI -->|telemetry| Collector
        TodosAPI -->|telemetry| Collector
        UsersAPI -->|telemetry| Collector

        subgraph "Integration Test Harness"
            direction TB
            TestHarness["API Integration Tests"]:::infra
        end

        TestHarness -->|calls| TodosAPI
        TestHarness -->|calls| UsersAPI
    end

    %% Click Events
    click UI "https://github.com/davidfowl/todoapp/tree/main/Todo.Web/Client"
    click SharedDTOs "https://github.com/davidfowl/todoapp/tree/main/Todo.Web/Shared"
    click AuthExtensions "https://github.com/davidfowl/todoapp/tree/main/Todo.Web/Server/Authentication"
    click AuthAPI "https://github.com/davidfowl/todoapp/blob/main/Todo.Web/Server/AuthApi.cs"
    click AuthClient "https://github.com/davidfowl/todoapp/blob/main/Todo.Web/Server/AuthClient.cs"
    click YARP "https://github.com/davidfowl/todoapp/blob/main/Todo.Web/Server/TodoApi.cs"
    click TodosAPI "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/Todos/TodoApi.cs"
    click UsersAPI "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/Users/UsersApi.cs"
    click DbContext "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/TodoDbContext.cs"
    click OpenAPI "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/Extensions/OpenApiOptionsExtensions.cs"
    click RateLimit "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/Extensions/RateLimitExtensions.cs"
    click Validation "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/Filters/ValidationFilter.cs"
    click AuthHandlers "https://github.com/davidfowl/todoapp/blob/main/Todo.Api/Authorization/CheckCurrentUserAuthHandler.cs"
    click TestHarness "https://github.com/davidfowl/todoapp/blob/main/Todo.Api.Tests"
    click AppHost "https://github.com/davidfowl/todoapp/blob/main/TodoApp.AppHost/Program.cs"
    click ServiceDefaults "https://github.com/davidfowl/todoapp/blob/main/TodoApp.ServiceDefaults/Extensions.cs"

    classDef frontend fill:#E0F7FA,stroke:#0288D1,stroke-width:2px
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
    classDef external fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px
    classDef infra fill:#FFF3E0,stroke:#F57C00,stroke-width:2px
```
