# gaesty/pokedex architecture

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

- Interactive diagram: https://gitdiagram.com/gaesty/pokedex
- Repository: https://github.com/gaesty/pokedex

## Overview

##### Project type and purpose
- This is a .NET 9 Web API (“PokeDex API”) built with ASP.NET Core and Entity Framework Core.
- It exposes REST endpoints for Pokémon data (abilities, species, moves, types, teams, media, weather) and authentication (JWT).
- It uses a PostgreSQL database for persistence, calls two external services (PokeAPI and a Weather API), and is containerized via Docker and Docker Compose.
- It emits Prometheus-style metrics (via prometheus-net) and is monitored by a Prometheus + Grafana stack.

##### File structure
- Top-level solution file (PokeDex.sln), Docker assets (Dockerfile, docker-compose.yml, docker_resources folder), Prometheus config, Postman test run, SQL scripts.
- Inside `BourgPalette/`:
- `Controllers/` – REST controllers by domain
- `Services/` – business-logic services (WeatherService, CachedWeatherService, PokeApiImporter, ITokenService)
- `Data/` – EF Core DbContext, migrations, DbSeeder
- `Middleware/` – global error handler
- `Program.cs` – pipeline setup (middleware, DI, health/metrics endpoints)
- `appsettings.json` – configuration (including JWT secret, connection strings)
- Monitoring and metrics code under `metrics/metrics.cs`.

##### Key architectural insights from README
- The system is deployed as three Docker containers:
1) the API
2) PostgreSQL
3) the Prometheus + Grafana monitoring stack (defined in docker-compose).
- Prometheus scrapes `/metrics` on the API; Grafana reads from Prometheus.
- External integrations: PokeAPI and Weather API over HTTP.
- Authentication is JWT-based.
- EF Core handles migrations and seeding at startup.

##### Detail level
- Middleware pipeline explicitly.
- Don’t shy away from showing both migrations and DbSeeder in the data layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients & Tools"
        direction TB
        Swagger["Swagger UI"]:::client
        Postman["Postman"]:::client
    end

    subgraph "API Container"
        direction TB
        Program["Program.cs"]:::service
        Middleware["ErrorHandlingMiddleware"]:::service
        AuthMiddleware["JWT Authentication"]:::service

        subgraph "Controllers"
            direction TB
            Abilities["AbilitiesController"]:::controller
            AuthC["AuthController"]:::controller
            CRUD["CRUDController"]:::controller
            Media["MediaController"]:::controller
            Moves["MovesController"]:::controller
            Species["SpeciesController"]:::controller
            Teams["TeamsController"]:::controller
            Types["TypesController"]:::controller
            WeatherC["WeatherController"]:::controller
        end

        subgraph "Services"
            direction TB
            IToken["ITokenService"]:::service
            WeatherSv["WeatherService"]:::service
            CachedWeather["CachedWeatherService"]:::service
            PokeImporter["PokeApiImporter"]:::service
        end

        subgraph "Data Layer"
            direction TB
            AppDb["ApplicationDbContext"]:::data
            DbSeeder["DbSeeder"]:::service
            DesignFactory["ApplicationDbContextFactory"]:::service
            Migrations["EF Core Migrations"]:::data
        end

        subgraph "Config & Metrics"
            direction TB
            AppSettings["appsettings.json"]:::config
            DevSettings["appsettings.Development.json"]:::config
            MetricsSetup["metrics.cs"]:::service
        end
    end

    subgraph "Database Container"
        direction TB
        Postgres["PostgreSQL"]:::db
    end

    subgraph "External Services"
        direction TB
        PokeAPI["PokeAPI"]:::external
        WeatherAPI["Weather API"]:::external
    end

    subgraph "Monitoring Stack"
        direction TB
        Prometheus["Prometheus"]:::monitor
        Grafana["Grafana"]:::monitor
    end

    Swagger -->|HTTP| Program
    Postman -->|HTTP| Program

    Program -->|uses| Middleware
    Middleware -->|auth pipeline| AuthMiddleware
    AuthMiddleware -->|dispatch| Abilities
    AuthMiddleware -->|dispatch| AuthC
    AuthMiddleware -->|dispatch| CRUD
    AuthMiddleware -->|dispatch| Media
    AuthMiddleware -->|dispatch| Moves
    AuthMiddleware -->|dispatch| Species
    AuthMiddleware -->|dispatch| Teams
    AuthMiddleware -->|dispatch| Types
    AuthMiddleware -->|dispatch| WeatherC

    Abilities -->|calls| IToken
    AuthC -->|calls| IToken
    CRUD -->|calls| AppDb
    Media -->|calls| PokeImporter
    Moves -->|calls| AppDb
    Species -->|calls| AppDb
    Teams -->|calls| AppDb
    Types -->|calls| AppDb
    WeatherC -->|calls| WeatherSv

    WeatherSv -->|HTTP GET| WeatherAPI
    WeatherC -->|calls| CachedWeather
    CachedWeather -->|uses| AppDb

    PokeImporter -->|HTTP GET| PokeAPI

    AppDb -->|SQL| Postgres
    DbSeeder -->|seed| Postgres
    Migrations -->|migrate| Postgres
    DesignFactory -->|creates| AppDb

    Program -->|exposes /metrics| MetricsSetup
    Prometheus -->|scrape /metrics| MetricsSetup
    Grafana -->|query| Prometheus

    %% Click Events
    click Program "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Program.cs"
    click Abilities "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/AbilitiesController.cs"
    click AuthC "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/AuthController.cs"
    click CRUD "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/CRUDController.cs"
    click Media "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/MediaController.cs"
    click Moves "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/MovesController.cs"
    click Species "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/SpeciesController.cs"
    click Teams "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/TeamsController.cs"
    click Types "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/TypesController.cs"
    click WeatherC "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Controllers/WeatherController.cs"
    click IToken "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Services/ITokenService.cs"
    click WeatherSv "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Services/WeatherService.cs"
    click CachedWeather "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Services/CachedWeatherService.cs"
    click PokeImporter "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Services/PokeApiImporter.cs"
    click AppDb "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Data/ApplicationDbContext.cs"
    click DbSeeder "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Data/DbSeeder.cs"
    click DesignFactory "https://github.com/gaesty/pokedex/blob/main/BourgPalette/Data/DesignTime/ApplicationDbContextFactory.cs"
    click Migrations "https://github.com/gaesty/pokedex/tree/main/BourgPalette/Migrations/"
    click MetricsSetup "https://github.com/gaesty/pokedex/blob/main/BourgPalette/metrics/metrics.cs"
    click AppSettings "https://github.com/gaesty/pokedex/blob/main/BourgPalette/appsettings.json"
    click DevSettings "https://github.com/gaesty/pokedex/blob/main/BourgPalette/appsettings.Development.json"
    click Postgres "https://github.com/gaesty/pokedex/blob/main/docker-compose.yml"
    click Prometheus "https://github.com/gaesty/pokedex/blob/main/prometheus.yml"
    click Grafana "https://github.com/gaesty/pokedex/blob/main/docker-compose.yml"
    click Swagger "https://github.com/gaesty/pokedex/blob/main/PokeDex API v1.postman_test_run.json"
    click Postman "https://github.com/gaesty/pokedex/blob/main/PokeDex API v1.postman_test_run.json"

    %% Styles
    classDef controller fill:#D0E8FF,stroke:#3399FF;
    classDef service fill:#E8F4D0,stroke:#66CC33;
    classDef data fill:#D0F0D8,stroke:#33CC66;
    classDef db fill:#D0FFD8,stroke:#33AA33,stroke-dasharray: 5 5;
    classDef external fill:#F0F0F0,stroke:#999999,stroke-dasharray: 2 2;
    classDef monitor fill:#FFE8A0,stroke:#FFAA33;
    classDef client fill:#E8D0FF,stroke:#AA33FF;
    classDef config fill:#FFF4D0,stroke:#CC9900;
```
