# zoxexivo/open-football architecture

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

- Interactive diagram: https://gitdiagram.com/zoxexivo/open-football
- Repository: https://github.com/zoxexivo/open-football

## Overview

##### Project Type and Purpose
- This is a full-stack simulation application (“Open Football”) that models soccer leagues, clubs, matches, training, transfers, etc., without manual control.
- It comprises:
- A Rust-based simulation engine (“core”)
- A Rust-based HTTP API/backend (“server”)
- A static/JSON data generator (“database” crate)
- An Angular frontend (“ui” folder)
- Optional experimental tooling (“neural” and “dev” crates for graphics and neural network experiments)

##### High-Level Architecture Components
- Frontend (Angular UI)
- Backend API (Rust server crate)
- Simulation Engine (Rust core crate)
- Data Layer (Rust database crate)
- Experimental Subsystems (Rust neural and dev crates)
- Infrastructure/CI (Dockerfile, Drone CI, run configurations)

##### Component Responsibilities and Technologies
a. UI (ui/)
- Angular app (TypeScript, HTML, SCSS)
- Modules for pages: countries, leagues, teams, players, matches
- Services to call REST endpoints on the backend
- Hosted on port 4200 in dev; served by backend in production

b. API Server (server/)
- Rust HTTP server (actix-web or similar via Cargo.toml)
- Routes organized by resource: countries, leagues, teams, players, matches, game processing, date
- Uses core crate for simulation logic and database crate for static data loading
- Listens on port 18000

c. Simulation Engine (src/core/)
- Domain model for club, league, match engine, transfers, training, etc.
- Organized by domain subpackages (club, league, match, transfers, utils)
- Exposes public API (lib.rs) used by server and dev tools

d. Data Generator/Loader (src/database/)
- Loads JSON files (clubs.json, continents.json, etc.)
- Provides “loader” modules to populate core domain types
- Optional “generator” modules to create synthetic players/staff

e. Experimental Tools (src/neural/, src/dev/)
- Neural: machine learning models for match decisions (binary model files + Rust wrappers)

f. Infrastructure
- build/Football.Dockerfile for containerization
- .drone.yml for CI pipelines
- .run/*.run.xml for IDE launch configurations
- Scripts for publishing and updating

##### Relationships and Data Flows
- User → Browser → Angular UI
- UI → HTTP REST endpoints on Server (GET /countries, /leagues, /matches/:id, POST /game/process)
- Server routes → invoke core simulation engine and data layer
- Simulation engine reads static data from database loaders and may consult neural models
- Results → JSON responses → UI renders pages or match play controls
- Docker wraps Server + UI in one container for production
- CI triggers tests/builds of core, database, server, neural, and ui modules

##### Architectural Patterns and Principles
- Layered architecture: Presentation (UI) → API layer → Domain layer (core) → Data layer (database)
- Modularization via Rust crates for strong boundaries and compile-time safety
- RESTful resource design on the API
- Domain-driven design: rich domain model for clubs, matches, leagues, etc.
- Experimental separation: neural and graphics modules do not pollute core domain

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI["Angular UI\n(port 4200)"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        API["Rust API Server\n(port 18000)"]:::backend
        API_routes["Routes:\ncountries, leagues,\nteams, players,\nmatches, game, date"]:::backend
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Core["Simulation Engine\n(Core Crate)"]:::core
        DB["Data Loader\n(Database Crate)\n(JSON data, loaders, generators)"]:::data
    end

    %% Experimental Tools
    subgraph "Experimental Tools"
        Neural["Neural Module\n(Optional ML)"]:::experimental
        DevGraphics["Dev Graphics Tool"]:::experimental
        DevNeural["Dev Neural Tool"]:::experimental
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Docker["Docker Container\n(build/Football.Dockerfile)"]:::infra
        CI["CI/CD (Drone CI)"]:::infra
        RunConfs["IDE Run Configurations\n(.run/)"]:::infra
        Scripts["Publish/Update Scripts\n(.scripts/)"]:::infra
    end

    %% Workspace Entrypoint
    Workspace["Workspace Entry\nsrc/main.rs"]:::infra

    %% Data Flows
    UI -->|"HTTP GET/POST\n(JSON)"| API
    API -->|"calls simulate_match()"| Core
    API -->|"loads static data"| DB
    Core -->|"load_data()"| DB
    Core -.->|"optional model query"| Neural
    DevGraphics -->|"uses Core API"| Core
    DevNeural -->|"uses Core API"| Core
    Core -->|"JSON responses"| API
    API -->|"JSON responses"| UI

    Docker --> UI
    Docker --> API
    CI --> UI
    CI --> API
    CI --> Core
    CI --> DB
    CI --> Neural
    CI --> DevGraphics
    CI --> DevNeural
    RunConfs --> UI
    RunConfs --> API
    RunConfs --> DevGraphics
    RunConfs --> DevNeural
    Scripts --> CI

    Workspace --> API
    Workspace --> Core
    Workspace --> DB
    Workspace --> Neural
    Workspace --> DevGraphics
    Workspace --> DevNeural

    %% Click Events
    click UI "https://github.com/zoxexivo/open-football/tree/master/ui/"
    click API "https://github.com/zoxexivo/open-football/tree/master/src/server/"
    click API_routes "https://github.com/zoxexivo/open-football/blob/master/src/server/src/routes.rs"
    click Core "https://github.com/zoxexivo/open-football/tree/master/src/core/"
    click DB "https://github.com/zoxexivo/open-football/tree/master/src/database/"
    click Neural "https://github.com/zoxexivo/open-football/tree/master/src/neural/"
    click DevGraphics "https://github.com/zoxexivo/open-football/tree/master/src/dev/graphics/"
    click DevNeural "https://github.com/zoxexivo/open-football/tree/master/src/dev/neural/"
    click Workspace "https://github.com/zoxexivo/open-football/blob/master/src/main.rs"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef backend fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef core fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef data fill:#CFD8DC,stroke:#455A64,color:#455A64
    classDef experimental fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef infra fill:#E0E0E0,stroke:#424242,color:#424242
```
