# foxy4096/pingville-web architecture

> Architecture diagram of the GitHub repository foxy4096/pingville-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/foxy4096/pingville-web
- Repository: https://github.com/foxy4096/pingville-web

## Overview

##### Project type and purpose
- From the README and file tree, Pingville Web is a PHP‐based companion website for a game (“PingVille”).
- It handles user accounts, authentication (login/signup/logout), token management, achievements, and exposes HTTP APIs for the game client to sync positions and query user data.

##### File structure
- Top‐level PHP scripts (index.php, login.php, signup.php, games.php, etc.) serve HTML pages to the browser.
- The `api/` directory contains REST‐style endpoints (login.php, sync_position.php, get_last_position.php, me.php) that the game client or AJAX calls from the frontend invoke.
- `templates/` holds shared HTML snippets (e.g., footer.php).
- `utils/` holds reusable backend logic (auth.php for authentication, users.php for user‐related database operations).
- `db.php` centralizes database connection logic; `query.sql` provides schema or seed data.
- `api/tasks/remove_expired_tokens.php` is likely intended as a cron‐style maintenance job for token cleanup.
- `script.js` and `styles.css` are the main frontend assets; pages reference these for client‐side behavior and styling.

##### README for additional insights
- The database is MySQL (or compatible) configured via an environment `_secrets.php` file.

##### Detail
- Database schema only if necessary (tables for users, tokens, achievements), but at minimum show “MySQL” and “Connections from PHP”.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        Browser["Web Browser UI"]:::client
        GameClient["Game Client"]:::client
    end

    %% Server Layer: PHP Web Application
    subgraph "PHP Web Application"
        direction TB
        subgraph "Page Controllers"
            direction TB
            Index["index.php"]:::page
            LoginPage["login.php"]:::page
            Signup["signup.php"]:::page
            Logout["logout.php"]:::page
            Games["games.php"]:::page
            Settings["settings.php"]:::page
            MePage["me.php"]:::page
            Download["download.php"]:::page
            Revoke["revoke_token.php"]:::page
            Goto["goto.php"]:::page
        end

        subgraph "API Controllers"
            direction TB
            APILogin["api/login.php"]:::api
            APISync["api/sync_position.php"]:::api
            APIGetLast["api/get_last_position.php"]:::api
            APIMe["api/me.php"]:::api
        end

        subgraph "Shared Modules"
            direction TB
            DBConn["db.php"]:::module
            Auth["utils/auth.php"]:::module
            Users["utils/users.php"]:::module
        end

        subgraph "Templates"
            Footer["templates/footer.php"]:::template
        end

        subgraph "Assets"
            Script["script.js"]:::asset
            Styles["styles.css"]:::asset
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        MySQL["MySQL Database"]:::infra
        Cron["Cron: remove_expired_tokens.php"]:::infra
    end

    %% Connections: Clients to Server
    Browser -->|"HTTP GET pages"| Index
    Browser -->|"HTTP GET pages"| LoginPage
    Browser -->|"HTTP GET pages"| Signup
    Browser -->|"HTTP GET pages"| Logout
    Browser -->|"HTTP GET pages"| Games
    Browser -->|"HTTP GET pages"| Settings
    Browser -->|"HTTP GET pages"| MePage
    Browser -->|"HTTP GET pages"| Download
    Browser -->|"HTTP POST revoke"| Revoke
    Browser -->|"HTTP GET goto"| Goto

    Browser -->|"AJAX/HTTP POST"| APILogin
    Browser -->|"AJAX/HTTP GET"| APIMe

    GameClient -->|"HTTP POST sync"| APISync
    GameClient -->|"HTTP GET last position"| APIGetLast

    %% Server internals
    Index --> Auth
    Index --> Users
    LoginPage --> Auth
    LoginPage --> Users
    Signup --> Auth
    Signup --> Users
    Logout --> Auth
    Games --> Users
    Settings --> Users
    MePage --> Users
    Download --> Users
    Revoke --> Auth
    Goto --> Users

    APILogin --> Auth
    APILogin --> Users
    APISync --> Users
    APISync --> DBConn
    APIGetLast --> Users
    APIMe --> Users

    %% DB interactions
    Auth --> MySQL
    Users --> MySQL
    DBConn --> MySQL

    %% Cron job
    Cron -->|"executes"| DBConn
    Cron --> MySQL

    %% Assets & Templates usage
    Index --> Script
    Index --> Styles
    LoginPage --> Script
    LoginPage --> Styles
    Signup --> Script
    Signup --> Styles
    Games --> Script
    Games --> Styles
    Settings --> Script
    Settings --> Styles
    MePage --> Script
    MePage --> Styles
    Download --> Styles
    Goto --> Styles

    Index --> Footer
    LoginPage --> Footer
    Signup --> Footer
    Games --> Footer
    Settings --> Footer
    MePage --> Footer

    %% Click Events for component mapping
    click Index "https://github.com/foxy4096/pingville-web/blob/main/index.php"
    click LoginPage "https://github.com/foxy4096/pingville-web/blob/main/login.php"
    click Signup "https://github.com/foxy4096/pingville-web/blob/main/signup.php"
    click Logout "https://github.com/foxy4096/pingville-web/blob/main/logout.php"
    click Games "https://github.com/foxy4096/pingville-web/blob/main/games.php"
    click Settings "https://github.com/foxy4096/pingville-web/blob/main/settings.php"
    click MePage "https://github.com/foxy4096/pingville-web/blob/main/me.php"
    click Download "https://github.com/foxy4096/pingville-web/blob/main/download.php"
    click Revoke "https://github.com/foxy4096/pingville-web/blob/main/revoke_token.php"
    click Goto "https://github.com/foxy4096/pingville-web/blob/main/goto.php"
    click APILogin "https://github.com/foxy4096/pingville-web/blob/main/api/login.php"
    click APISync "https://github.com/foxy4096/pingville-web/blob/main/api/sync_position.php"
    click APIGetLast "https://github.com/foxy4096/pingville-web/blob/main/api/get_last_position.php"
    click APIMe "https://github.com/foxy4096/pingville-web/blob/main/api/me.php"
    click DBConn "https://github.com/foxy4096/pingville-web/blob/main/db.php"
    click Auth "https://github.com/foxy4096/pingville-web/blob/main/utils/auth.php"
    click Users "https://github.com/foxy4096/pingville-web/blob/main/utils/users.php"
    click Footer "https://github.com/foxy4096/pingville-web/blob/main/templates/footer.php"
    click Script "https://github.com/foxy4096/pingville-web/blob/main/script.js"
    click Styles "https://github.com/foxy4096/pingville-web/blob/main/styles.css"
    click Cron "https://github.com/foxy4096/pingville-web/blob/main/api/tasks/remove_expired_tokens.php"

    %% Styles
    classDef client fill:#D6EAF8,stroke:#3498DB,color:#154360
    classDef page fill:#FDEDEC,stroke:#E74C3C,color:#78281F
    classDef api fill:#E8F8F5,stroke:#1ABC9C,color:#0E6251
    classDef module fill:#FEF9E7,stroke:#F1C40F,color:#7D6608
    classDef template fill:#F4ECF7,stroke:#9B59B6,color:#4A235A
    classDef asset fill:#EBF5FB,stroke:#5DADE2,color:#1B4F72
    classDef infra fill:#F2F3F4,stroke:#B3B6B7,color:#424949
```
