# renatoamado/pokemon-symfony architecture

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

- Interactive diagram: https://gitdiagram.com/renatoamado/pokemon-symfony
- Repository: https://github.com/renatoamado/pokemon-symfony

## Overview

##### Project type and purpose
- This is a full-stack PHP web application built on the Symfony framework.
- It exposes a browser-accessible UI (Twig templates + static assets) and communicates with an external Pokémon TCG API to fetch card data.
- It persists data locally via Doctrine ORM and supports caching to improve performance.

##### Main components
a. Infrastructure / Deployment layer (Docker Compose)
- Nginx reverse-proxy (SSL termination)
- PHP-FPM container running the Symfony application
- Database container (e.g. MySQL/PostgreSQL from DATABASE_URL)
b. Entry point & Routing
- public/index.php (Symfony front controller)
- Symfony HTTP Kernel (config/routes + src/Controller)
c. Presentation layer (Frontend)
- Twig templates (templates/*.twig)
- Static assets: app.js, app.css (assets/)
d. Application layer (Backend services)
- Controllers (src/Controller/PokemonController.php)
- Services & Interfaces (PokemonService, CardProvider, CacheService, NonceGenerator)
- Transformers & DTOs (src/Transformer, src/DataTransferObject)
e. Domain / Persistence
- Entities (src/Entity) + Repositories (src/Repository)
- Doctrine Migrations (migrations/)
f. External systems
- Pokémon TCG API (pokemontcg.io) accessed via Pokémon TCG SDK

##### Relationships & data flow
- Browser → HTTPS request to Nginx → forwarded to PHP-FPM/Symfony
- Symfony front controller → Router → Controller
- Controller calls PokemonService →
- First, CacheService to check local cache (Doctrine)
- If cache miss, CardProvider calls external API via SDK
- Result wrapped in CardDTO, passed through Transformer
- Transformed data returned to Controller
- Controller renders Twig template, sending HTML back to browser
- On certain operations (e.g. caching), repositories persist entities to the database

##### Architectural patterns & design principles
- MVC (Controllers → Views via Twig)
- Layered/Hexagonal architecture (Controllers → Services → Repositories → DB)
- Dependency Injection (services configured in config/services.yaml)
- Interface-driven contracts (ServiceInterface for all core services)
- DTO & Transformer pattern to decouple API response from domain model

- Top layer: Browser → (HTTPS) Nginx
- Next: PHP-FPM / Symfony front controller
- Routing: config/routes.yaml → Controller
- Application services: PokemonServiceInterface → implementations (CacheService, CardProvider, NonceGenerator)
- Transformation: TransformerInterface → DTOs
- Persistence: Doctrine Repository → Database
- External: Pokémon TCG SDK → HTTP calls to pokemontcg.io
- Build/config scripts: composer, Dockerfiles, docker-compose.yml

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend / UI"
        direction TB
        Browser["Browser"]:::frontend
        JS["app.js"]:::frontend
        CSS["app.css"]:::frontend
        Browser -->|loads| JS
        Browser -->|loads| CSS
        Browser -->|HTTP Request| Nginx
    end

    %% Infrastructure Layer
    subgraph "Infrastructure / Deployment" 
        direction TB
        Nginx["Nginx (SSL Termination)"]:::infra
        PHPFPM["PHP-FPM Container"]:::infra
        DatabaseContainer["Database Container"]:::infra
        Nginx -->|forward| PHPFPM
        PHPFPM -->|connects| DatabaseContainer
    end

    %% Entry Point & Routing
    subgraph "Entry Point & Routing" 
        direction TB
        FrontController["public/index.php"]:::backend
        Routes["config/routes.yaml\n(+ imports)"]:::backend
        Router["Symfony Router"]:::backend
        FrontController -->|bootstrap| Router
        Router -->|match route| Controller
    end

    %% Application Layer
    subgraph "Application Services" 
        direction TB
        Controller["PokemonController"]:::backend
        Service["PokemonService"]:::backend
        CacheService["CacheService"]:::backend
        CardProvider["CardProvider"]:::backend
        Transformer["Transformer"]:::backend
        DTO["CardDTO"]:::backend
        Controller -->|calls| Service
        Service -->|check cache| CacheService
        CacheService -->|query| Repository
        Service -->|fetch card| CardProvider
        CardProvider -->|SDK call| ExternalAPI
        CardProvider -->|wrap result| DTO
        DTO -->|transform| Transformer
        Transformer -->|return data| Controller
        Controller -->|render| Twig
    end

    %% Presentation Templates
    subgraph "Twig Templates" 
        direction TB
        Base["templates/base.html.twig"]:::frontend
        IndexView["templates/pokemon/index.html.twig"]:::frontend
        ShowView["templates/pokemon/show.html.twig"]:::frontend
        Controller -->|render view| Base
        Controller -->|render view| IndexView
        Controller -->|render view| ShowView
    end

    %% Domain / Persistence
    subgraph "Persistence / DB" 
        direction TB
        Repository["Doctrine Repositories\n(src/Repository)"]:::database
        Entity["Doctrine Entities\n(src/Entity)"]:::database
        Repository -->|persist| Database
    end
    Database["Database"]:::database

    %% External Systems
    ExternalAPI["Pokémon TCG API\n(pokemontcg.io)"]:::external
    ExternalAPI -->|returns JSON| CardProvider

    %% Infrastructure Config
    subgraph "Docker Config" 
        direction TB
        Compose["docker-compose.yml"]:::infra
        NginxConf[".docker/nginx/default.conf"]:::infra
        SSLcert[".docker/nginx/ssl/cert.pem\nkey.pem"]:::infra
        PHPDocker[".docker/php/Dockerfile\nphp.ini\n90-xdebug.ini"]:::infra
        Compose --> NginxConf
        Compose --> SSLcert
        Compose --> PHPDocker
    end

    %% Test Suites
    subgraph "Testing" 
        direction TB
        FeatureTest["tests/Feature/Controller/PokemonControllerTest.php"]:::backend
        IntegrationTest["tests/Integration/PokemonServiceTest.php"]:::backend
        UnitTest1["tests/Unit/CacheServiceTest.php"]:::backend
        UnitTest2["tests/Unit/CardProviderTest.php"]:::backend
        UnitTest3["tests/Unit/TransformerTest.php"]:::backend
    end

    %% Click events
    click JS "https://github.com/renatoamado/pokemon-symfony/blob/main/assets/app.js"
    click CSS "https://github.com/renatoamado/pokemon-symfony/blob/main/assets/styles/app.css"
    click FrontController "https://github.com/renatoamado/pokemon-symfony/blob/main/public/index.php"
    click Routes "https://github.com/renatoamado/pokemon-symfony/blob/main/config/routes.yaml"
    click Controller "https://github.com/renatoamado/pokemon-symfony/blob/main/src/Controller/PokemonController.php"
    click Base "https://github.com/renatoamado/pokemon-symfony/blob/main/templates/base.html.twig"
    click IndexView "https://github.com/renatoamado/pokemon-symfony/blob/main/templates/pokemon/index.html.twig"
    click ShowView "https://github.com/renatoamado/pokemon-symfony/blob/main/templates/pokemon/show.html.twig"
    click Service "https://github.com/renatoamado/pokemon-symfony/blob/main/src/Service/PokemonService.php"
    click CacheService "https://github.com/renatoamado/pokemon-symfony/blob/main/src/Service/CacheService.php"
    click CardProvider "https://github.com/renatoamado/pokemon-symfony/blob/main/src/Service/CardProvider.php"
    click DTO "https://github.com/renatoamado/pokemon-symfony/blob/main/src/DataTransferObject/CardDTO.php"
    click Transformer "https://github.com/renatoamado/pokemon-symfony/blob/main/src/Transformer/Transformer.php"
    click Repository "https://github.com/renatoamado/pokemon-symfony/tree/main/src/Repository"
    click Compose "https://github.com/renatoamado/pokemon-symfony/blob/main/docker-compose.yml"
    click NginxConf "https://github.com/renatoamado/pokemon-symfony/blob/main/.docker/nginx/default.conf"
    click SSLcert "https://github.com/renatoamado/pokemon-symfony/blob/main/.docker/nginx/ssl/cert.pem"
    click PHPDocker "https://github.com/renatoamado/pokemon-symfony/tree/main/.docker/php/Dockerfile"
    click FeatureTest "https://github.com/renatoamado/pokemon-symfony/blob/main/tests/Feature/Controller/PokemonControllerTest.php"
    click IntegrationTest "https://github.com/renatoamado/pokemon-symfony/blob/main/tests/Integration/PokemonServiceTest.php"
    click UnitTest1 "https://github.com/renatoamado/pokemon-symfony/blob/main/tests/Unit/CacheServiceTest.php"
    click UnitTest2 "https://github.com/renatoamado/pokemon-symfony/blob/main/tests/Unit/CardProviderTest.php"
    click UnitTest3 "https://github.com/renatoamado/pokemon-symfony/blob/main/tests/Unit/TransformerTest.php"

    %% Styles
    classDef frontend fill:#DDA0DD,stroke:#800080,color:#000000
    classDef backend fill:#ADD8E6,stroke:#0000FF,color:#000000
    classDef database fill:#FFA500,stroke:#FF8C00,color:#000000
    classDef external fill:#90EE90,stroke:#008000,color:#000000
    classDef infra fill:#D3D3D3,stroke:#808080,color:#000000
```
