# gusev03/brawlpick architecture

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

- Interactive diagram: https://gitdiagram.com/gusev03/brawlpick
- Repository: https://github.com/gusev03/brawlpick

## Overview

##### Project Type and Purpose
- This is a full-stack analytics application comprising two distinct layers:
– A Python “data-collection” service (scripts + Postgres) that pulls raw game data from the external Brawl Stars API, stores it, and emits aggregated JSON.
– A Next.js + Tailwind CSS “frontend” that visualizes that data as a static site (reads JSON from /public).

##### High-Level Architecture Components
- External Service: Brawl Stars REST API
- Data-Collection Service (Python)
– Scripts: brawl_stars_api.py (API client), database.py (Postgres ORM/wrapper), main.py (entrypoint), utility scripts (cleanup, pull_analytics, etc.)
– Environment: .venv, requirements.txt, .env for DB/API credentials
- Database: PostgreSQL instance
- Data Artifacts: JSON files under data-collection/data/ → moved into frontend/public/data/
- Frontend App (Next.js)
– Static assets: JSON data, images, game_maps, ranks
– Code: page.tsx templates under src/app/[gameMode]/[mapName] etc., components (MapImage.tsx), global layout, Tailwind CSS config
- User’s Web Browser

##### Data Flows & Interactions
- (1) Python Data-Collection Service authenticates to Brawl Stars API → retrieves raw battle and trophy data
- (2) Service writes raw and processed records to PostgreSQL
- (3) “pull_analytics” script queries Postgres → generates summary JSON in data-collection/data/
- (4) Developer copies JSON into frontend/public/data/
- (5) Next.js dev/build server reads JSON files at compile time or runtime → renders pages under /[gameMode]/[mapName]
- (6) End-user’s browser loads HTML/CSS/JS from Next.js server (localhost:3000 or deployed URL) → fetches additional JSON as needed → displays analytics dashboards

##### Architectural Patterns & Design Principles
- Separation of Concerns:
– Data-ingestion layer (Python + Postgres) is entirely decoupled from presentation (Next.js).
- Data Pipeline:
- File-based Routing: Next.js conventions map JSON assets to dynamic routes.
- Static-First Deployment: JSON and images live in /public, enabling CDN caching and no runtime backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    BSAPI["Brawl Stars REST API"]:::external

    %% Data-Collection Subsystem
    subgraph "Data-Collection Service"
        direction TB
        DC_ENV[".env / requirements.txt / .gitignore"]:::compute
        VENV[".venv"]:::compute
        API_CLIENT["brawl_stars_api.py"]:::compute
        DB_MODULE["database.py"]:::compute
        ENTRY["main.py"]:::compute
        subgraph "Utility & Export Scripts"
            direction TB
            SCRIPTS["scripts/"]:::compute
        end
        DATA_OUT["data/*.json"]:::data
    end

    %% Database
    Postgres["PostgreSQL (v13)"]:::data

    %% Frontend Subsystem
    subgraph "Frontend (Next.js + Tailwind)"
        direction TB
        PUBLIC_DATA["public/data/*.json"]:::data
        GAME_MAPS["public/game_maps/"]:::data
        RANKS["public/ranks/"]:::data
        subgraph "Application Code"
            direction TB
            ROUTE_PAGE["[gameMode]/[mapName]/page.tsx"]:::compute
            ROUTE_INDEX["[gameMode]/page.tsx"]:::compute
            FAQ["faq/page.tsx"]:::compute
            ROOT_PAGE["page.tsx"]:::compute
            LAYOUT["layout.tsx / globals.css"]:::compute
            COMPONENT["components/MapImage.tsx"]:::compute
        end
        subgraph "Config & Manifest"
            direction TB
            NEXTCFG["next.config.ts"]:::compute
            ESLINT[".eslintrc.json"]:::compute
            TAILWIND["tailwind.config.ts"]:::compute
            POSTCSS["postcss.config.mjs"]:::compute
            TSCONFIG["tsconfig.json"]:::compute
            PKG["package.json / package-lock.json"]:::compute
        end
        NextServer["Next.js Server"]:::compute
    end

    %% User Client
    Browser["User Browser"]:::client

    %% Data Flows
    BSAPI -->|GET battle data| API_CLIENT
    API_CLIENT -->|uses| DB_MODULE
    API_CLIENT -->|INSERT/SELECT| Postgres
    ENTRY -->|orchestrates| API_CLIENT
    ENTRY -->|orchestrates| DB_MODULE
    ENTRY -->|runs| SCRIPTS
    SCRIPTS -->|EXPORT JSON| DATA_OUT
    DC_ENV -->|config| ENTRY
    VENV -->|environment| ENTRY
    DATA_OUT -->|COPY| PUBLIC_DATA
    PUBLIC_DATA -->|BUILD/TIME READ| ROUTE_PAGE
    PUBLIC_DATA -->|BUILD/TIME READ| ROUTE_INDEX
    PUBLIC_DATA -->|BUILD/TIME READ| FAQ
    PUBLIC_DATA -->|BUILD/TIME READ| ROOT_PAGE
    GAME_MAPS -->|SERVE STATIC| NextServer
    RANKS -->|SERVE STATIC| NextServer
    NextServer -->|SERVE HTML/CSS/JS| Browser
    Browser -->|FETCH JSON| PUBLIC_DATA

    %% Click Events
    click API_CLIENT "https://github.com/gusev03/brawlpick/blob/main/data-collection/brawl_stars_api.py"
    click DB_MODULE "https://github.com/gusev03/brawlpick/blob/main/data-collection/database.py"
    click ENTRY "https://github.com/gusev03/brawlpick/blob/main/data-collection/main.py"
    click SCRIPTS "https://github.com/gusev03/brawlpick/tree/main/data-collection/scripts/"
    click DC_ENV "https://github.com/gusev03/brawlpick/blob/main/data-collection/requirements.txt"
    click DC_ENV "https://github.com/gusev03/brawlpick/blob/main/data-collection/.env.example"
    click DC_ENV "https://github.com/gusev03/brawlpick/blob/main/data-collection/.gitignore"
    click VENV "https://github.com/gusev03/brawlpick/tree/main/data-collection/"
    click DATA_OUT "https://github.com/gusev03/brawlpick/tree/main/data-collection/data/"
    click PUBLIC_DATA "https://github.com/gusev03/brawlpick/tree/main/frontend/public/data/"
    click GAME_MAPS "https://github.com/gusev03/brawlpick/tree/main/frontend/public/game_maps/"
    click RANKS "https://github.com/gusev03/brawlpick/tree/main/frontend/public/ranks/"
    click ROUTE_PAGE "https://github.com/gusev03/brawlpick/blob/main/frontend/src/app/[gameMode]/[mapName]/page.tsx"
    click ROUTE_INDEX "https://github.com/gusev03/brawlpick/blob/main/frontend/src/app/[gameMode]/page.tsx"
    click FAQ "https://github.com/gusev03/brawlpick/blob/main/frontend/src/app/faq/page.tsx"
    click ROOT_PAGE "https://github.com/gusev03/brawlpick/blob/main/frontend/src/app/page.tsx"
    click LAYOUT "https://github.com/gusev03/brawlpick/blob/main/frontend/src/app/layout.tsx"
    click COMPONENT "https://github.com/gusev03/brawlpick/blob/main/frontend/src/components/MapImage.tsx"
    click NEXTCFG "https://github.com/gusev03/brawlpick/blob/main/frontend/next.config.ts"
    click ESLINT "https://github.com/gusev03/brawlpick/blob/main/frontend/.eslintrc.json"
    click TAILWIND "https://github.com/gusev03/brawlpick/blob/main/frontend/tailwind.config.ts"
    click POSTCSS "https://github.com/gusev03/brawlpick/blob/main/frontend/postcss.config.mjs"
    click TSCONFIG "https://github.com/gusev03/brawlpick/blob/main/frontend/tsconfig.json"
    click PKG "https://github.com/gusev03/brawlpick/blob/main/frontend/package.json"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef data fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef client fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
