# afiiif/pokemon-world architecture

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

- Interactive diagram: https://gitdiagram.com/afiiif/pokemon-world
- Repository: https://github.com/afiiif/pokemon-world

## Overview

##### Main components
- Client/Frontend: This includes all user-facing components built with React, found under src/components and the various feature directories under src/features (e.g., compare-pokemons, guess-pokemon, pokemon-detail, pokemon-list, statistics).
- Next.js Pages & Routing: The pages directory (under src/pages) handles the composition of these React components into individual pages (e.g., index.tsx, pokemon/[...slug].tsx). This layer also includes API routes found in src/pages/api that act as server endpoints.
- API Layer / Data Fetching: Within src/api, you have a dedicated place for queries (using GraphQL) that interact with the external PokeAPI, along with configuration for react-query (src/config/react-query.ts) and related hooks.
- Build and Configuration: Elements such as the Next.js configuration (next.config.js, next-pwa.cache.js, next-sitemap.config.js), Tailwind CSS (tailwind.config.js and PostCSS configurations), and TypeScript settings (tsconfig.json) set the foundation for the build and runtime environment.
- Development, Testing, and Quality Controls: Note the existence of development tooling (such as ESLint, Prettier, Husky with commit hooks, GitHub Actions workflows, and end-to-end e2e tests in the e2e folder and playwright.config.ts).

##### Relationships and data flow
- The Client/Frontend sends requests (fetched via src/api/fetcher.ts) to the API endpoints (pages/api) when data needs to be fetched or manipulated.
- The API endpoints communicate with the external PokeAPI GraphQL service, using GraphQL queries defined in src/api/queries, to retrieve Pokémon data.
- The returned data flows back to frontend components that render pages based on the Next.js routing.

##### Important architectural patterns and design principles
- Separation of Concerns: Clear separation between client-side UI (React components and pages) and backend data fetching via API endpoints.
- Modular Feature-Based Structure: The src/features directory is broken down by domain (like compare-pokemons, guess-pokemon, etc.), which assists in maintainability and scalability.
- API Abstraction: Data queries are abstracted into their own modules (under src/api/queries), facilitating easier changes to external data sources.
- Integration of CI/CD and Code Quality: The presence of Husky, Lint-Staged, GitHub Actions, and other tooling suggests a workflow that emphasizes quality assurance throughout the development lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js + React UI)"
        FE_components["React Components [src/components]"]:::frontend
        FE_features["Feature Modules [src/features]"]:::frontend
    end

    %% Pages & Routing
    subgraph "Next.js Pages & Routing"
        Pages["Pages [src/pages]"]:::pages
        API_endpoints["API Endpoints [src/pages/api]"]:::pages
    end

    %% API Layer / Data Fetching
    subgraph "API Layer / Data Fetching"
        Fetcher["Fetcher [src/api/fetcher.ts]"]:::api
        Queries["GraphQL Queries [src/api/queries]"]:::api
        REACTQUERY["React Query Config [src/config/react-query.ts]"]:::api
    end

    %% External Services & Static Assets
    subgraph "External Services & Assets"
        External["PokeAPI GraphQL Service"]:::external
        Static["Static Assets [public]"]:::external
    end

    %% Build & Dev Tools
    subgraph "Build & Dev Tools"
        NEXTCONF["Next.js Config [next.config.js, next-pwa.cache.js, next-sitemap.config.js]"]:::build
        TAILWIND["Tailwind & Styles [tailwind.config.js, postcss.config.js, src/styles]"]:::build
        TS["TypeScript [tsconfig.json]"]:::build
        DEVTOOLS["Dev & Quality Tools [Husky, ESLint, Prettier, GitHub Actions]"]:::build
    end

    %% Testing
    subgraph "Testing"
        E2E["E2E Tests [e2e, playwright.config.ts]"]:::dev
    end

    %% Data Flow from Frontend to API and back
    FE_features -->|"fetch_data"| API_endpoints
    API_endpoints -->|"request"| Fetcher
    API_endpoints -->|"setup"| REACTQUERY
    Fetcher -->|"use"| Queries
    Queries -->|"query"| External
    External -->|"return"| Queries
    Queries -->|"return"| Fetcher
    Fetcher -->|"respond"| API_endpoints
    Pages -->|"render"| FE_components
    FE_components ---|"display"| Pages
    Static -->|"serve"| FE_components

    %% Build & Dev Tools supporting connections
    NEXTCONF --- Pages
    TAILWIND --- Pages
    TS --- Pages
    DEVTOOLS --- NEXTCONF
    DEVTOOLS --- TAILWIND
    DEVTOOLS --- TS
    DEVTOOLS --- API_endpoints
    DEVTOOLS --- FE_components
    DEVTOOLS --- FE_features
    DEVTOOLS --- Pages
    DEVTOOLS --- REACTQUERY
    DEVTOOLS --- Fetcher
    DEVTOOLS --- Queries
    E2E --- DEVTOOLS

    %% Click Events
    click FE_components "https://github.com/afiiif/pokemon-world/tree/main/src/components"
    click FE_features "https://github.com/afiiif/pokemon-world/tree/main/src/features"
    click Pages "https://github.com/afiiif/pokemon-world/tree/main/src/pages"
    click API_endpoints "https://github.com/afiiif/pokemon-world/tree/main/src/pages/api"
    click Fetcher "https://github.com/afiiif/pokemon-world/blob/main/src/api/fetcher.ts"
    click Queries "https://github.com/afiiif/pokemon-world/tree/main/src/api/queries"
    click REACTQUERY "https://github.com/afiiif/pokemon-world/blob/main/src/config/react-query.ts"
    click Static "https://github.com/afiiif/pokemon-world/tree/main/public"
    click NEXTCONF "https://github.com/afiiif/pokemon-world/blob/main/next.config.js"
    click TAILWIND "https://github.com/afiiif/pokemon-world/blob/main/tailwind.config.js"
    click TS "https://github.com/afiiif/pokemon-world/blob/main/tsconfig.json"
    click DEVTOOLS "https://github.com/afiiif/pokemon-world/blob/main/.husky"
    click E2E "https://github.com/afiiif/pokemon-world/tree/main/e2e"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef pages fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef api fill:#dcedc8,stroke:#7cb342,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef build fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
    classDef dev fill:#f8bbd0,stroke:#d81b60,stroke-width:2px;

    class FE_components,FE_features frontend;
    class Pages,API_endpoints pages;
    class Fetcher,Queries,REACTQUERY api;
    class External,Static external;
    class NEXTCONF,TAILWIND,TS,DEVTOOLS build;
    class E2E dev;
```
