# holgadom/nest-pokedex architecture

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

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

## Overview

##### Project Type and Purpose
- This is a modular monolith backend service written in NestJS, exposing a REST API for “Pokemon” resources, alongside a simple seed‐data endpoint. It also serves static assets from the `public` directory. It uses MongoDB for persistence and relies on an external Pokemon API during seeding.

##### File Structure Highlights
- Top level: Docker orchestrator (`docker-compose.yaml`), environment template (`.env.example`), Nest CLI config, lint & formatting rules, `public/` (static frontend).
- `src/` modular breakdown:
- `common/` – shared adapters (Axios HTTP client), DTOs, pipes (MongoID parser), interfaces
- `config/` – environment config & Joi validation
- `pokemon/` – controller, service, DTOs, entity schema
- `seed/` – controller, service, interfaces for external API response
- `app.module.ts` & `main.ts` – NestJS bootstrap
- Tests under `test/`, TypeScript build configs.

##### Key Architectural Patterns
- NestJS Modules for logical boundaries
- Layered design: Controller → Service → Adapter/Repository → Database
- Dependency injection for adapters & config
- Adapter pattern for HTTP (Axios) calls to external services
- Configuration module validated by Joi
- Docker Compose manages the NestJS app and MongoDB instance

a. External Clients & Static UI
- Browser / API consumer
- `public/index.html` & CSS (optional static UI)
b. API Gateway (NestJS HTTP Server)
- Main NestJS instance (port 3000)
- Request routing by controllers (`PokemonController`, `SeedController`)
c. Business Logic Layer
- `PokemonService`: CRUD operations against MongoDB
- `SeedService`: fetches from external Pokemon API via `AxiosAdapter`, transforms & writes to DB
d. Shared/Common Layer
- `AxiosAdapter`: implements `HttpAdapter` interface
- Pipes (e.g., `ParseMongoIdPipe`)
- DTOs & validation
e. Data Storage
- MongoDB container (as defined in `docker-compose.yaml`)
- Collections: `pokemon`
f. External Dependencies
- Public Pokemon REST API (seed source)

##### Relationships & Data Flow
- Client → HTTP request → NestJS Controller → Service → (DB via Mongoose/TypeORM)
- Seed flow: Controller → SeedService → AxiosAdapter → External API → data mapping → MongoDB
- Environment config injected at startup via `ConfigModule` → used by adapters & DB connector

## Diagram (Mermaid)

```mermaid
graph TB
  %% External Clients & Static UI
  subgraph "External Interface"
    direction TB
    Client["Browser / API Consumer"]:::client
    StaticUI["public/index.html & CSS"]:::static
  end

  %% API Gateway Layer
  subgraph "API Gateway (NestJS HTTP Server)"
    direction TB
    MainTS["main.ts"]:::api
    AppModule["app.module.ts"]:::api
    ControllerGroup["Controllers"]:::api
    ControllerGroup --> PokemonController
    ControllerGroup --> SeedController
  end

  PokemonController["PokemonController"]:::api
  SeedController["SeedController"]:::api

  %% Business Logic Layer
  subgraph "Business Logic"
    direction TB
    PokemonModule["Pokemon Module"]:::api
    SeedModule["Seed Module"]:::api

    PokemonModule --> PokemonService
    PokemonModule --> PokemonController
    PokemonModule --> PokemonDTOs
    PokemonModule --> PokemonEntity

    SeedModule --> SeedService
    SeedModule --> SeedController
    SeedModule --> SeedInterfaces
  end

  PokemonService["PokemonService"]:::api
  SeedService["SeedService"]:::api

  PokemonDTOs["Pokemon DTOs"]:::api
  PokemonEntity["Pokemon Entity Schema"]:::api
  SeedInterfaces["Seed Response Interfaces"]:::api

  %% Shared/Common Layer
  subgraph "Common / Shared"
    direction TB
    CommonModule["Common Module"]:::common
    AxiosAdapter["AxiosAdapter"]:::common
    HttpAdapterIF["HttpAdapter Interface"]:::common
    PipesGroup["Pipes & DTOs"]:::common
    ConfigModule["Configuration & Validation"]:::common
  end

  PipesGroup --> ParseMongoIdPipe
  PipesGroup --> CommonDTOs

  ParseMongoIdPipe["ParseMongoIdPipe"]:::common
  CommonDTOs["Common DTOs"]:::common
  ConfigModule["Config & Joi Validation"]:::common

  %% Data Storage & External API
  subgraph "Infrastructure"
    direction TB
    MongoDB["MongoDB"]:::db
    ExternalAPI["Public Pokemon REST API"]:::ext
    DockerCompose["Docker Compose (App & MongoDB)"]:::infra
  end

  %% Relationships & Data Flow
  Client -->|HTTP GET/POST| PokemonController
  Client -->|HTTP GET| SeedController
  Client -->|GET| StaticUI

  PokemonController -->|calls| PokemonService
  SeedController -->|calls| SeedService

  PokemonService -->|CRUD via Mongoose| MongoDB
  SeedService -->|calls| AxiosAdapter
  AxiosAdapter -->|HTTP GET| ExternalAPI
  SeedService -->|writes| MongoDB

  ConfigModule -->|injects config| AppModule
  AppModule -->|imports| ConfigModule
  AppModule -->|imports| CommonModule
  AppModule -->|imports| PokemonModule
  AppModule -->|imports| SeedModule

  %% Click Events
  click StaticUI "https://github.com/holgadom/nest-pokedex/blob/main/public/index.html"
  click Client "https://github.com/holgadom/nest-pokedex/blob/main/public/css/style.css"
  click MainTS "https://github.com/holgadom/nest-pokedex/blob/main/src/main.ts"
  click AppModule "https://github.com/holgadom/nest-pokedex/blob/main/src/app.module.ts"
  click PokemonController "https://github.com/holgadom/nest-pokedex/blob/main/src/pokemon/pokemon.controller.ts"
  click PokemonService "https://github.com/holgadom/nest-pokedex/blob/main/src/pokemon/pokemon.service.ts"
  click PokemonModule "https://github.com/holgadom/nest-pokedex/blob/main/src/pokemon/pokemon.module.ts"
  click PokemonDTOs "https://github.com/holgadom/nest-pokedex/blob/main/src/pokemon/dto/create-pokemon.dto.ts"
  click PokemonDTOs "https://github.com/holgadom/nest-pokedex/blob/main/src/pokemon/dto/update-pokemon.dto.ts"
  click PokemonEntity "https://github.com/holgadom/nest-pokedex/blob/main/src/pokemon/entities/pokemon.entity.ts"
  click SeedController "https://github.com/holgadom/nest-pokedex/blob/main/src/seed/seed.controller.ts"
  click SeedService "https://github.com/holgadom/nest-pokedex/blob/main/src/seed/seed.service.ts"
  click SeedModule "https://github.com/holgadom/nest-pokedex/blob/main/src/seed/seed.module.ts"
  click SeedInterfaces "https://github.com/holgadom/nest-pokedex/blob/main/src/seed/interfaces/poke-response.interface.ts"
  click AxiosAdapter "https://github.com/holgadom/nest-pokedex/blob/main/src/common/adapters/axios.adapter.ts"
  click HttpAdapterIF "https://github.com/holgadom/nest-pokedex/blob/main/src/common/interfaces/http-adapter.interface.ts"
  click CommonModule "https://github.com/holgadom/nest-pokedex/blob/main/src/common/common.module.ts"
  click CommonDTOs "https://github.com/holgadom/nest-pokedex/blob/main/src/common/dto/pagination.dto.ts"
  click ParseMongoIdPipe "https://github.com/holgadom/nest-pokedex/blob/main/src/common/pipes/parse-mongo-id/parse-mongo-id.pipe.ts"
  click ConfigModule "https://github.com/holgadom/nest-pokedex/blob/main/src/config/app.config.ts"
  click ConfigModule "https://github.com/holgadom/nest-pokedex/blob/main/src/config/joi.validation.ts"
  click DockerCompose "https://github.com/holgadom/nest-pokedex/blob/main/docker-compose.yaml"
  click NestCLI "https://github.com/holgadom/nest-pokedex/blob/main/nest-cli.json"
  click Env "https://github.com/holgadom/nest-pokedex/blob/main/ .env.example"

  %% Styles
  classDef api fill:#cce5ff,stroke:#2b7bb9,color:#000;
  classDef db fill:#d4edda,stroke:#28a745,color:#000;
  classDef ext fill:#e2e3e5,stroke:#6c757d,color:#000;
  classDef client fill:#fff3cd,stroke:#ffc107,color:#000;
  classDef static fill:#f8d7da,stroke:#dc3545,color:#000;
  classDef common fill:#ffe5b4,stroke:#ff9900,color:#000;
  classDef infra fill:#d1ecf1,stroke:#17a2b8,color:#000;
```
