# masnat/pokedex-api architecture

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

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

## Overview

##### Project Type and Purpose
- This project is a Python-based web application that exposes a REST API to serve Pokémon data.
- It is composed of two main functionalities: crawling data from an external Pokémon site and then serving that data via a RESTful API.
- The project interacts with a PostgreSQL database which stores Pokémon information.

##### Main Components of the System
- Data Crawler & ETL Scripts:
- Files: crawl_pokedex.py, generate_table.py, and truncate_table.py.
- Purpose: Creating the required database schema, populating it with data crawled from an external source (the Pokémon Dex website), and the ability to truncate/refresh the data.
- Database Connector:
- File: conn.py.
- Purpose: Contains the database configuration and connection logic for PostgreSQL.
- REST API Server:
- File: server.py.
- Purpose: Runs the web server that exposes the REST API endpoints for listing all Pokémon, querying specific details, or retrieving a random Pokémon.
- Database (External Component):
- PostgreSQL database named “pokedex” storing the Pokémon data.

##### Relationships and Interactions
- The "generate_table.py" script is executed to create the necessary tables in the PostgreSQL database.
- The "crawl_pokedex.py" script uses the database connector (conn.py) to populate the tables by scraping the external Pokémon Dex website.
- "truncate_table.py" provides maintenance capability if data reset/cleanup is needed.
- The "server.py" script starts the REST API, which connects (using conn.py’s configuration) to the PostgreSQL database. The API handles various query parameters and routes to deliver Pokémon data.
- External Source: The crawler fetches data from the public "Pokemon Dex" website.

##### Architectural Patterns and Design Principles
- Layered Architecture:
- Data Access Layer: Database connector (conn.py) and the underlying PostgreSQL.
- Business/Data Processing Layer: Data crawling and table management scripts.
- Presentation/API Layer: REST API server (server.py).
- Clear separation of concerns is maintained between data ingestion (crawling and table generation) and data serving (API).
- Use of external libraries and tools such as Requests for HTTP queries, BeautifulSoup for parsing HTML, SQLAlchemy for database interactions, and psycopg2 as the PostgreSQL driver.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion Layer"
        subgraph "ETL Scripts"
            GT["generate_table.py"]:::etl
            CP["crawl_pokedex.py"]:::etl
            TT["truncate_table.py"]:::etl
        end
    end

    Conn["conn.py"]:::connector
    subgraph "Presentation/API Layer"
        API["server.py"]:::api
    end
    PD["PostgreSQL Database (pokedex)"]:::database
    ES["External Pokémon Dex Source"]:::external

    ES -->|"fetches_data"| CP
    GT -->|"creates_schema"| Conn
    CP -->|"scrapes_data"| Conn
    TT -->|"truncates_data"| Conn
    API -->|"queries_data"| Conn
    Conn -->|"connects_to"| PD

    click GT "https://github.com/masnat/pokedex-api/blob/main/generate_table.py"
    click CP "https://github.com/masnat/pokedex-api/blob/main/crawl_pokedex.py"
    click TT "https://github.com/masnat/pokedex-api/blob/main/truncate_table.py"
    click Conn "https://github.com/masnat/pokedex-api/blob/main/conn.py"
    click API "https://github.com/masnat/pokedex-api/blob/main/server.py"

    classDef etl fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef api fill:#c9daf8,stroke:#1155cc,stroke-width:2px;
    classDef connector fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef database fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef external fill:#ead1dc,stroke:#b854a1,stroke-width:2px;
```
