How gusev03/brawlpick works
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.