# matteocrielesi/f1-projectgame architecture

> Architecture diagram of the GitHub repository matteocrielesi/f1-projectgame, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matteocrielesi/f1-projectgame
- Repository: https://github.com/matteocrielesi/f1-projectgame

## Overview

1. This is a Flutter-based, client-only F1 arcade game with no backend service in the repository. The same Dart codebase targets Web, Android, Windows, macOS, Linux, and iOS, with platform shells generated by Flutter around the shared app logic.

2. The app entry and navigation flow appear to be `main.dart` → splash/boot UI (`splash_page.dart`) → a pre-game/menu screen (`game_page_0.dart`) → the main play screen (`lib/game/screens/game_screen.dart`). The README confirms the main documented experience is the Challenge mode.

3. The central runtime boundary is the game controller layer in `lib/game/controllers/game_controller.dart`. This is likely the orchestrator that owns game state, selected circuit, vehicle state, lap timing, race progression, and restart/retry behavior.

4. The domain model is split into `Car` and `Circuit` under `lib/game/models/`. These objects represent the core game entities that the controller and physics layer operate on, rather than being UI-only state.

5. Track content is data-driven from JSON assets under `assets/circuiti/track/`. Each circuit has its own track file, which suggests geometry/layout is loaded at runtime instead of being hardcoded. The `mask` folder likely supports track boundaries or collision/driveable-area detection.

6. Motion and interaction rules are isolated in `lib/game/utils/physics.dart`. This is the gameplay math layer: acceleration, braking, steering, timing, and probably simple collision or off-track handling. `start_lights.dart` suggests a pre-race countdown subsystem that gates when the player can start moving.

7. Presentation is concentrated in `lib/game/screens/` and `lib/game/widgets/`. `game_screen.dart` is the main play surface, while `game_controls.dart` provides the touch/keyboard controls that feed player input into the controller. The UI is therefore a thin layer over the game state.

8. Persistence is abstracted through `lib/game/saves/game_records.dart` with separate platform implementations: `game_records_impl_io.dart` and `game_records_impl_web.dart`. This is an important architectural boundary because record storage is platform-specific, likely using local file/system storage on desktop/mobile and browser storage on Web.

9. The asset model is broad and game-specific: `assets/logos`, `assets/macchine`, `assets/piloti`, and the circuit JSONs. That indicates the game is content-rich and visually branded, with the gameplay logic separate from the visual/theme assets.

10. Platform directories (`android`, `ios`, `macos`, `linux`, `windows`, `web`) are mostly standard Flutter wrappers, but the repo also includes web-specific static files like `web/index.html`, `web/manifest.json`, and splash assets. These define the browser packaging and PWA surface for the Web build.

11. CI/CD is a first-class operational subsystem in `.github/workflows/`. The repository automatically builds and publishes Android APKs, Windows EXEs, and web builds to GitHub Pages; tagged releases on `main` produce release artifacts, while pushes to `main` deploy the web build.

12. The `scripts/increment_version.*` files support release/version automation, matching the workflow-driven release process. In architecture terms, versioning is treated as part of the delivery pipeline rather than a manual packaging step.

13. Tests exist but are minimal in scope (`test/widget_test.dart`, plus default platform test scaffolding). The repository’s main architectural emphasis is on gameplay logic, asset-driven track content, and multi-platform distribution rather than a large test or service layer.

Main entry points: [`lib/game/controllers/game_controller.dart`](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/controllers/game_controller.dart) (Game controller), [`lib/main.dart`](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/main.dart) (Main), [`.github/workflows`](https://github.com/matteocrielesi/f1-projectgame/blob/main/.github/workflows) (Workflows), [`lib/game/screens/game_screen.dart`](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/screens/game_screen.dart) (Game screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Shared app"]
  node_main["Main<br/>entry<br/>[main.dart]"]
  node_splash["Splash<br/>ui screen<br/>[splash_page.dart]"]
  node_menu["Game menu<br/>ui screen<br/>[game_page_0.dart]"]
end

subgraph group_gameplay["Gameplay engine"]
  node_game_screen["Game screen<br/>play screen<br/>[game_screen.dart]"]
  node_controller["Game controller<br/>orchestrator"]
  node_physics{{"Physics<br/>rules engine<br/>[physics.dart]"}}
  node_start_lights(("Start lights<br/>countdown<br/>[start_lights.dart]"))
  node_controls["Controls<br/>input ui<br/>[game_controls.dart]"]
  node_car["Car<br/>model<br/>[car.dart]"]
  node_circuit["Circuit<br/>model<br/>[circuit.dart]"]
  node_records["Game records<br/>storage api<br/>[game_records.dart]"]
  node_records_io["Records IO<br/>storage impl"]
  node_records_web["Records web<br/>storage impl"]
end

subgraph group_content["Content"]
  node_track_assets[("Track JSON<br/>asset data")]
  node_visual_assets[("Visual assets<br/>asset pack")]
end

subgraph group_delivery["Delivery"]
  node_workflows{{"Workflows<br/>ci/cd<br/>[workflows]"}}
  node_versioning["Versioning<br/>release script"]
end

subgraph group_platforms["Platform shells"]
  node_android_shell["Android shell<br/>platform wrapper"]
  node_ios_shell["iOS shell<br/>platform wrapper"]
  node_macos_shell["macOS shell<br/>platform wrapper"]
  node_linux_shell["Linux shell<br/>platform wrapper"]
  node_windows_shell["Windows shell<br/>platform wrapper"]
  node_web_shell["Web shell<br/>platform wrapper"]
end

node_main -->|"boots"| node_splash
node_splash -->|"navigates"| node_menu
node_menu -->|"starts game"| node_game_screen
node_game_screen -->|"drives"| node_controller
node_controls -->|"inputs"| node_controller
node_controller -->|"uses"| node_physics
node_controller -->|"gates"| node_start_lights
node_controller -->|"owns"| node_car
node_controller -->|"selects"| node_circuit
node_controller -->|"persists"| node_records
node_records -->|"implements"| node_records_io
node_records -->|"implements"| node_records_web
node_circuit -->|"loads"| node_track_assets
node_game_screen -->|"renders"| node_visual_assets
node_android_shell -->|"hosts"| node_main
node_ios_shell -->|"hosts"| node_main
node_macos_shell -->|"hosts"| node_main
node_linux_shell -->|"hosts"| node_main
node_windows_shell -->|"hosts"| node_main
node_web_shell -->|"hosts"| node_main
node_workflows -->|"builds"| node_android_shell
node_workflows -->|"builds"| node_windows_shell
node_workflows -->|"deploys"| node_web_shell
node_versioning -->|"supports"| node_workflows

click node_main "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/main.dart"
click node_splash "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/splash_page.dart"
click node_menu "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game_page_0.dart"
click node_game_screen "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/screens/game_screen.dart"
click node_controller "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/controllers/game_controller.dart"
click node_physics "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/utils/physics.dart"
click node_start_lights "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/start_lights.dart"
click node_controls "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/widgets/game_controls.dart"
click node_car "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/models/car.dart"
click node_circuit "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/models/circuit.dart"
click node_records "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/saves/game_records.dart"
click node_records_io "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/saves/game_records_impl_io.dart"
click node_records_web "https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/saves/game_records_impl_web.dart"
click node_track_assets "https://github.com/matteocrielesi/f1-projectgame/tree/main/assets/circuiti/track"
click node_visual_assets "https://github.com/matteocrielesi/f1-projectgame/tree/main/assets"
click node_android_shell "https://github.com/matteocrielesi/f1-projectgame/tree/main/android"
click node_ios_shell "https://github.com/matteocrielesi/f1-projectgame/tree/main/ios"
click node_macos_shell "https://github.com/matteocrielesi/f1-projectgame/tree/main/macos"
click node_linux_shell "https://github.com/matteocrielesi/f1-projectgame/tree/main/linux"
click node_windows_shell "https://github.com/matteocrielesi/f1-projectgame/tree/main/windows"
click node_web_shell "https://github.com/matteocrielesi/f1-projectgame/tree/main/web"
click node_workflows "https://github.com/matteocrielesi/f1-projectgame/blob/main/.github/workflows"
click node_versioning "https://github.com/matteocrielesi/f1-projectgame/blob/main/scripts/increment_version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_splash,node_menu toneBlue
class node_game_screen,node_controller,node_physics,node_start_lights,node_controls,node_car,node_circuit,node_records,node_records_io,node_records_web toneAmber
class node_track_assets,node_visual_assets toneMint
class node_workflows,node_versioning toneRose
class node_android_shell,node_ios_shell,node_macos_shell,node_linux_shell,node_windows_shell,node_web_shell toneIndigo
```

## Components

### Shared app

Flutter app logic shared across all targets.

- [Main](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/main.dart): entry · App bootstrap and top-level navigation entry. · `lib/main.dart`
- [Splash](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/splash_page.dart): ui screen · Boot/loading screen before the game flow. · `lib/splash_page.dart`
- [Game menu](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game_page_0.dart): ui screen · Pre-game selection and challenge entry screen. · `lib/game_page_0.dart`

### Gameplay engine

Game state, rules, models, and runtime flow.

- [Game screen](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/screens/game_screen.dart): play screen · Main gameplay surface and in-race presentation. · `lib/game/screens/game_screen.dart`
- [Game controller](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/controllers/game_controller.dart): orchestrator · Owns race state, progression, retries, and selected circuit. · `lib/game/controllers/game_controller.dart`
- [Physics](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/utils/physics.dart): rules engine · Motion, steering, timing, and gameplay math. · `lib/game/utils/physics.dart`
- [Start lights](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/start_lights.dart): countdown · Pre-race start gate and launch timing. · `lib/start_lights.dart`
- [Controls](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/widgets/game_controls.dart): input ui · Touch and keyboard input surface for the player. · `lib/game/widgets/game_controls.dart`
- [Car](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/models/car.dart): model · Vehicle state and attributes used by the controller and physics. · `lib/game/models/car.dart`
- [Circuit](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/models/circuit.dart): model · Track selection and circuit metadata. · `lib/game/models/circuit.dart`
- [Game records](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/saves/game_records.dart): storage api · Abstraction for saving and loading records. · `lib/game/saves/game_records.dart`
- [Records IO](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/saves/game_records_impl_io.dart): storage impl · Platform persistence implementation for desktop/mobile. · `lib/game/saves/game_records_impl_io.dart`
- [Records web](https://github.com/matteocrielesi/f1-projectgame/blob/main/lib/game/saves/game_records_impl_web.dart): storage impl · Browser persistence implementation for Web. · `lib/game/saves/game_records_impl_web.dart`

### Content

Asset-driven track and visual data.

- [Track JSON](https://github.com/matteocrielesi/f1-projectgame/tree/main/assets/circuiti/track): asset data · Circuit geometry and layout definitions loaded at runtime. · `assets/circuiti/track`
- [Visual assets](https://github.com/matteocrielesi/f1-projectgame/tree/main/assets): asset pack · Branded cars, drivers, logos, and related game art. · `assets`

### Delivery

Build, release, and version automation.

- [Workflows](https://github.com/matteocrielesi/f1-projectgame/blob/main/.github/workflows): ci/cd · Build, release, and deployment automation. · `.github/workflows`
- [Versioning](https://github.com/matteocrielesi/f1-projectgame/blob/main/scripts/increment_version.py): release script · Automated version bumping for releases and builds. · `scripts/increment_version.py`

### Platform shells

Generated wrappers and platform entry points.

- [Android shell](https://github.com/matteocrielesi/f1-projectgame/tree/main/android): platform wrapper · Android host project and launcher entry point. · `android`
- [iOS shell](https://github.com/matteocrielesi/f1-projectgame/tree/main/ios): platform wrapper · iOS host project and launcher entry point. · `ios`
- [macOS shell](https://github.com/matteocrielesi/f1-projectgame/tree/main/macos): platform wrapper · macOS host project and launcher entry point. · `macos`
- [Linux shell](https://github.com/matteocrielesi/f1-projectgame/tree/main/linux): platform wrapper · Linux host project and launcher entry point. · `linux`
- [Windows shell](https://github.com/matteocrielesi/f1-projectgame/tree/main/windows): platform wrapper · Windows host project and launcher entry point. · `windows`
- [Web shell](https://github.com/matteocrielesi/f1-projectgame/tree/main/web): platform wrapper · Web entry page, manifest, and splash packaging. · `web`

## Connections

- Main → Splash: boots · Application starts in the splash flow.
- Splash → Game menu: navigates · Boot screen transitions into pre-game selection.
- Game menu → Game screen: starts game · Challenge flow enters the main play screen.
- Game screen → Game controller: drives · Gameplay UI is orchestrated by the controller.
- Controls → Game controller: inputs · Player input feeds race state and movement decisions.
- Game controller → Physics: uses · Controller applies gameplay motion and timing rules.
- Game controller → Start lights: gates · Race launch is gated by countdown state.
- Game controller → Car: owns · Controller tracks the active vehicle state.
- Game controller → Circuit: selects · Controller manages the chosen circuit and track.
- Game controller → Game records: persists · Controller reads and writes race records.
- Game records → Records IO: implements · Native persistence backend.
- Game records → Records web: implements · Web persistence backend.
- Circuit → Track JSON: loads · Circuits are data-driven from JSON track files.
- Game screen → Visual assets: renders · Gameplay and branding rely on game assets.
- Android shell → Main: hosts · Android wrapper launches the shared Dart app.
- iOS shell → Main: hosts · iOS wrapper launches the shared Dart app.
- macOS shell → Main: hosts · macOS wrapper launches the shared Dart app.
- Linux shell → Main: hosts · Linux wrapper launches the shared Dart app.
- Windows shell → Main: hosts · Windows wrapper launches the shared Dart app.
- Web shell → Main: hosts · Web packaging launches the shared Dart app.
- Workflows → Android shell: builds · CI produces Android artifacts.
- Workflows → Windows shell: builds · CI produces Windows artifacts.
- Workflows → Web shell: deploys · CI publishes web builds to Pages.
- Versioning → Workflows: supports · Version bumping is part of the release pipeline.
