# woodong-222/pokeface-api architecture

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

- Interactive diagram: https://gitdiagram.com/woodong-222/pokeface-api
- Repository: https://github.com/woodong-222/pokeface-api

## Overview

##### Project type and purpose
- This is a backend-only, API-first web service written in PHP, augmented by a Python script for face-recognition/embedding.
- The API (“Pokéface-api”) assigns and evolves a unique Pokémon for each user by analyzing face embeddings on repeated recognition.

##### File structure
- Top-level files:
- Dockerfile, start.sh, nginx-php.conf, php.ini – deployment & runtime configuration
- composer.json/lock – PHP dependencies
- requirements.txt – Python dependencies
- config/ – middleware, headers, env config
- db/db.php – database connection
- api/ – all REST endpoints, grouped by resource (community, pokemon, user, register, login, password, notices)
- scripts/ – machine-learning helpers (face_embedding.py, register_developer_face.php)
- Patterns:
- MVC-style routing within `api/` (each .php file is a controller action)
- A thin Python microservice for face embedding steps, triggered from PHP

##### README
- Confirms high-level purpose: AI-driven face recognition, Pokémon assignment & evolution.

a. Main components:
- Client(s): Web/Mobile apps
- Reverse Proxy & Web Server: Nginx → PHP-FPM
- PHP Application Layer:
· Routing (api/)
· Business logic (community, pokemon, user modules)
· Auth middleware (config/auth_middleware.php)
- ML Microservice: Python face_embedding.py (script accepts image, returns embedding & closest Pokémon match)
- Database: relational (MySQL or MariaDB via db/db.php)
- File Storage: User face images & Pokémon avatars (local FS or network share)
b. Relationships & interactions:
- Client → HTTPS → Nginx
- Nginx → PHP-FPM → application code
- On “capture” or “upload” endpoints: PHP code calls the Python script (either via CLI or a lightweight RPC)
- Python script returns embedding; PHP persists/queries matching data in DB
- DB returns user’s Pokémon data; PHP responds to client
- Community endpoints read/write posts & likes in DB
c. Architectural patterns & design principles:
- Separation of concerns:
· Routing/controllers (api/) vs. config vs. data layer (db/) vs. ML layer (scripts/)
- Single responsibility: each PHP endpoint handles one resource operation
- Middleware for authentication (JWT or session)
- Microservice pattern for ML logic (Python script)
d. Key technologies/frameworks:
- PHP 7+ with Composer packages (e.g., JWT, database ORM)
- Nginx + PHP-FPM
- MySQL/MariaDB
- Python (face_embedding.py using face-recognition library)
- Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    WebClient["Web Client"]:::client
    MobileClient["Mobile Client"]:::client

    %% Reverse Proxy & App Server
    WebClient -->|HTTPS| NginxPHP["Nginx + PHP-FPM\n(80/443)"]:::compute
    MobileClient -->|HTTPS| NginxPHP

    %% Authentication Middleware
    NginxPHP --> AuthMiddleware["Auth Middleware"]:::config

    %% API Endpoints
    AuthMiddleware --> Controllers["Routing / Controllers\n(api/)"]:::compute

    subgraph "Routing / Controllers (api/)"
        direction TB
        subgraph "Community Module"
            direction TB
            Community_Create["create.php"]:::compute
            Community_Delete["delete.php"]:::compute
            Community_Like["like.php"]:::compute
            Community_Posts["posts.php"]:::compute
            Community_Upload["upload.php"]:::compute
        end
        subgraph "Pokémon Module"
            direction TB
            Pokemon_Album["album.php"]:::compute
            Pokemon_Capture["capture.php"]:::compute
            Pokemon_User["user_pokemon.php"]:::compute
        end
        subgraph "User Module"
            direction TB
            User_Me["me.php"]:::compute
        end
        subgraph "Register Module"
            direction TB
            Register_Register["register.php"]:::compute
            Register_Nickname["nickname.php"]:::compute
        end
        subgraph "Authentication / Login"
            direction TB
            Login["login.php"]:::compute
        end
        subgraph "Password Module"
            direction TB
            Password_Find["find.php"]:::compute
            Password_Reset["reset.php"]:::compute
        end
        subgraph "Notices Endpoint"
            direction TB
            Notices["notices.php"]:::compute
        end
    end

    %% Persistence & Services
    Controllers --> DB
    Controllers --> FileStorage
    Controllers --> FaceScript
    Pokemon_Capture --> FaceScript
    FaceScript --> DB
    Community_Upload --> FileStorage
    Pokemon_Album --> FileStorage

    %% Configuration
    subgraph "Config (config/)"
        direction TB
        AuthMiddleware
        EnvConfig["env_config.php"]:::config
        HeaderConfig["header.php"]:::config
    end

    %% Database
    DB["MySQL/MariaDB\n(db/db.php)"]:::db

    %% File Storage
    FileStorage["File Storage\n(user images & avatars)"]:::storage

    %% ML Microservice
    subgraph "ML Microservice (scripts/)"
        direction TB
        FaceScript["face_embedding.py"]:::script
        DevFace["register_developer_face.php"]:::script
    end

    %% Dependencies
    subgraph "Dependencies"
        direction TB
        ComposerJSON["composer.json"]:::deployment
        ComposerLock["composer.lock"]:::deployment
        Requirements["requirements.txt"]:::deployment
    end

    %% Deployment Config
    subgraph "Deployment & Runtime"
        direction TB
        Dockerfile["Dockerfile"]:::deployment
        StartSh["start.sh"]:::deployment
        NginxConf["nginx-php.conf"]:::deployment
        PHPCnf["php.ini"]:::deployment
    end

    %% Click Events
    click Community_Create "https://github.com/woodong-222/pokeface-api/blob/main/api/community/create.php"
    click Community_Delete "https://github.com/woodong-222/pokeface-api/blob/main/api/community/delete.php"
    click Community_Like "https://github.com/woodong-222/pokeface-api/blob/main/api/community/like.php"
    click Community_Posts "https://github.com/woodong-222/pokeface-api/blob/main/api/community/posts.php"
    click Community_Upload "https://github.com/woodong-222/pokeface-api/blob/main/api/community/upload.php"
    click Pokemon_Album "https://github.com/woodong-222/pokeface-api/blob/main/api/pokemon/album.php"
    click Pokemon_Capture "https://github.com/woodong-222/pokeface-api/blob/main/api/pokemon/capture.php"
    click Pokemon_User "https://github.com/woodong-222/pokeface-api/blob/main/api/pokemon/user_pokemon.php"
    click User_Me "https://github.com/woodong-222/pokeface-api/blob/main/api/user/me.php"
    click Register_Register "https://github.com/woodong-222/pokeface-api/blob/main/api/register/register.php"
    click Register_Nickname "https://github.com/woodong-222/pokeface-api/blob/main/api/register/nickname.php"
    click Login "https://github.com/woodong-222/pokeface-api/blob/main/api/login.php"
    click Password_Find "https://github.com/woodong-222/pokeface-api/blob/main/api/password/find.php"
    click Password_Reset "https://github.com/woodong-222/pokeface-api/blob/main/api/password/reset.php"
    click Notices "https://github.com/woodong-222/pokeface-api/blob/main/api/notices.php"
    click AuthMiddleware "https://github.com/woodong-222/pokeface-api/blob/main/config/auth_middleware.php"
    click EnvConfig "https://github.com/woodong-222/pokeface-api/blob/main/config/env_config.php"
    click HeaderConfig "https://github.com/woodong-222/pokeface-api/blob/main/config/header.php"
    click DB "https://github.com/woodong-222/pokeface-api/blob/main/db/db.php"
    click FaceScript "https://github.com/woodong-222/pokeface-api/blob/main/scripts/face_embedding.py"
    click DevFace "https://github.com/woodong-222/pokeface-api/blob/main/scripts/register_developer_face.php"
    click Dockerfile "https://github.com/woodong-222/pokeface-api/tree/main/Dockerfile"
    click StartSh "https://github.com/woodong-222/pokeface-api/blob/main/start.sh"
    click NginxConf "https://github.com/woodong-222/pokeface-api/blob/main/nginx-php.conf"
    click PHPCnf "https://github.com/woodong-222/pokeface-api/blob/main/php.ini"
    click ComposerJSON "https://github.com/woodong-222/pokeface-api/blob/main/composer.json"
    click ComposerLock "https://github.com/woodong-222/pokeface-api/blob/main/composer.lock"
    click Requirements "https://github.com/woodong-222/pokeface-api/blob/main/requirements.txt"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef db fill:#C3FDB8,stroke:#333,stroke-width:1px
    classDef storage fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef config fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef script fill:#FFE4C4,stroke:#333,stroke-width:1px
    classDef client fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef deployment fill:#E6E6FA,stroke:#333,stroke-width:1px
```
