# andi-nev/brawl-ai architecture

> Architecture diagram of the GitHub repository andi-nev/brawl-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andi-nev/brawl-ai
- Repository: https://github.com/andi-nev/brawl-ai

## Overview

##### Main Components
- Frontend:
- Built with Next.js (using TypeScript and React) and styled with TailwindCSS.
- Contains UI components (as seen in the “frontend/app/components” folder) including API handler, display components for brawlers and maps, and overall page routing/layout.
- Backend:
- A Python service likely using FastAPI (hinted by the README badge) for its web server (see backend/src/web_server.py).
- Contains various modules for AI processing (ai.py, inference.py, pipeline.py), data handling (datasource.py, db.py, feeding.py), and external integrations (scraper.py, old_ai.py for legacy functionality).
- Database:
- While not explicitly shown as a folder (and being optional for local testing), the README indicates PostgreSQL is used.
- Backend module “db.py” manages database interactions, particularly for training and feeding processes.
- External Services:
- Brawl Stars API (for live game data) and BrawlAPI for high-quality images, as mentioned in the README.
- These should be noted as external integrations that feed data into the backend.

##### Relationships and Interactions
- User requests flow from the frontend (Next.js UI) to the backend (FastAPI web server) via RESTful API calls.
- The backend performs AI-based decision making (handled in modules like ai.py, inference.py) and interacts with the PostgreSQL database to retrieve or store data.
- A data ingestion pipeline is present in the backend (using scraper.py and feeding.py), ensuring the system is regularly updated with fresh game data.
- The external services (Brawl Stars API, BrawlAPI) supply additional game assets and metrics that the system may use in its decision-making processes.

##### Architectural Patterns and Design Principles
- Separation of concerns is clear: the frontend and backend are independently managed, with a clear API boundary between them.
- Modular design in the backend, where different Python modules handle AI, data handling, and scraping; this suggests a deferred process pipeline typical in data-driven applications.
- The design also incorporates flexibility for model training and updating, inviting potential for scalability (e.g., swap or improve the AI model without interrupting the UI).

##### Technologies and Their Roles
- Frontend: Next.js, React, TypeScript, TailwindCSS – Serve as the mobile-friendly, responsive UI layer.
- Backend: Python, FastAPI (inferred), PyTorch – Provide AI capabilities and data processing.
- Database: PostgreSQL – Used (optionally) to store training data and game-related statistics.
- Others: ESLint and configuration files on the frontend; Git and project dependency files ensure standardized development and deployment pipelines.

- Under the backend, create sub-components for “AI Engine” (including ai.py, inference.py, pipeline.py), “Data Handling” (datasource.py, db.py, feeding.py, scraper.py), and “Legacy Module” (old_ai.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    client["Client"]:::external

    subgraph "Frontend Layer"
        FE_layout["Layout (frontend/app/layout.tsx)"]:::frontend
        FE_page["Page (frontend/app/page.tsx)"]:::frontend
        FE_components["UI Components (frontend/app/components)"]:::frontend
        FE_API["API Handler (frontend/app/components/api-handler.tsx)"]:::frontend
    end

    subgraph "Backend Layer"
        BE_webserver["FastAPI Server (backend/src/web_server.py)"]:::backend

        subgraph "AI Engine"
            BE_ai["ai.py"]:::module
            BE_inference["inference.py"]:::module
            BE_pipeline["pipeline.py"]:::module
        end

        subgraph "Data Handling"
            BE_datasource["datasource.py"]:::module
            BE_feeding["feeding.py"]:::module
            BE_scraper["scraper.py"]:::module
            BE_db["Database Interaction (backend/src/db.py)"]:::db
        end

        BE_legacy["Legacy AI Module (backend/src/old_ai.py)"]:::module
    end

    External["External Services (Brawl Stars API, BrawlAPI)"]:::external
    DB["Database (PostgreSQL)"]:::db

    client --> FE_components
    FE_components --> FE_API
    FE_API --> BE_webserver

    BE_webserver --> BE_ai
    BE_webserver --> BE_inference
    BE_webserver --> BE_pipeline
    BE_webserver --> BE_datasource
    BE_webserver --> BE_feeding
    BE_webserver --> BE_scraper
    BE_webserver --> BE_legacy

    External --> BE_datasource
    External --> BE_feeding
    External --> BE_scraper

    BE_datasource --> DB
    BE_feeding --> DB
    BE_scraper --> DB

click FE_components "https://github.com/andi-nev/brawl-ai/tree/main/frontend/app/components"
click FE_layout "https://github.com/andi-nev/brawl-ai/blob/main/frontend/app/layout.tsx"
click FE_page "https://github.com/andi-nev/brawl-ai/blob/main/frontend/app/page.tsx"
click FE_API "https://github.com/andi-nev/brawl-ai/blob/main/frontend/app/components/api-handler.tsx"
click BE_webserver "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/web_server.py"
click BE_ai "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/ai.py"
click BE_inference "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/inference.py"
click BE_pipeline "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/pipeline.py"
click BE_datasource "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/datasource.py"
click BE_feeding "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/feeding.py"
click BE_scraper "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/scraper.py"
click BE_db "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/db.py"
click BE_legacy "https://github.com/andi-nev/brawl-ai/blob/main/backend/src/old_ai.py"

classDef frontend fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
classDef backend fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
classDef module fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
classDef db fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
