# kipla1/bitwaveascend architecture

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

- Interactive diagram: https://gitdiagram.com/kipla1/bitwaveascend
- Repository: https://github.com/kipla1/bitwaveascend

## Overview

Bitwave Ascend is a C++ 2D game project, but the README says this checkout is repository initialization only: gameplay, authentication, payments, and persistence are not implemented. The intended user journey is frontend interaction through the shared GameAPI into backend game and account services, with progression and economy backed by persistence. The graph preserves those documented capabilities as planned subsystems; source excerpts confirm selected auth and payment dependencies, but do not establish full runtime wiring.

Main entry points: [`backend/src/core/GameAPIImpl.cpp`](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/core/GameAPIImpl.cpp) (Game API implementation), [`backend/src/payment/PaymentServiceImpl.cpp`](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/PaymentServiceImpl.cpp) (Purchase service), [`backend/src/persistence`](https://github.com/kipla1/bitwaveascend/tree/main/backend/src/persistence) (Data repositories), [`backend/include/core/GameManager.h`](https://github.com/kipla1/bitwaveascend/blob/main/backend/include/core/GameManager.h) (Game manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App boundary"]
  node_frontend["SFML frontend<br/>[main.cpp]"]
  node_contract["Shared contracts<br/>[Contracts.h]"]
  node_api["Game API<br/>[GameAPI.h]"]
  node_api_impl["Game API implementation<br/>[GameAPIImpl.cpp]"]
end

subgraph group_game["Game systems"]
  node_game_core["Game core"]
  node_game_manager["Game manager<br/>[GameManager.h]"]
  node_fighting["Fighting mode<br/>[FightingMode.h]"]
  node_running["Endless runner<br/>[RunningMode.h]"]
  node_flappy["Flappy mode<br/>[FlappyMode.h]"]
  node_gameplay_systems["Gameplay systems"]
  node_entities["Game entities"]
end

subgraph group_identity["Identity and progression"]
  node_auth["Authentication"]
  node_session["Login session<br/>[Session.h]"]
  node_alias["Alias service"]
  node_profile["Player profile"]
end

subgraph group_economy["Virtual economy"]
  node_payment["Purchase service"]
  node_store["Store<br/>[StoreImpl.cpp]"]
  node_wallet["Wallet<br/>[WalletImpl.cpp]"]
  node_inventory["Inventory<br/>[Inventory.cpp]"]
end

subgraph group_data["Persistence"]
  node_database[("SQLite database<br/>[Database.cpp]")]
  node_repositories["Data repositories"]
end

node_player(("Player"))

node_player -->|"interacts with"| node_frontend
node_frontend -->|"uses"| node_api
node_api -->|"shares types"| node_contract
node_api -.->|"implemented by"| node_api_impl
node_api_impl -.->|"dispatches to"| node_game_core
node_game_core -.->|"manages"| node_game_manager
node_game_manager -.->|"selects mode"| node_fighting
node_game_manager -.->|"selects mode"| node_running
node_game_manager -.->|"selects mode"| node_flappy
node_game_core -.->|"uses systems"| node_gameplay_systems
node_gameplay_systems -.->|"updates entities"| node_entities
node_api_impl -.->|"handles account flow"| node_auth
node_auth -->|"starts or ends"| node_session
node_auth -->|"creates and looks up"| node_repositories
node_alias -.->|"updates aliases"| node_repositories
node_api_impl -.->|"reports progression"| node_profile
node_profile -.->|"reads and updates"| node_repositories
node_api_impl -.->|"handles purchases"| node_payment
node_payment -.->|"uses"| node_store
node_payment -.->|"uses"| node_wallet
node_payment -.->|"uses"| node_inventory
node_payment -.->|"records transactions"| node_repositories
node_repositories -.->|"persists through"| node_database

click node_frontend "https://github.com/kipla1/bitwaveascend/blob/main/frontend/src/main.cpp"
click node_contract "https://github.com/kipla1/bitwaveascend/blob/main/shared/include/shared/Contracts.h"
click node_api "https://github.com/kipla1/bitwaveascend/blob/main/shared/include/shared/GameAPI.h"
click node_api_impl "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/core/GameAPIImpl.cpp"
click node_game_core "https://github.com/kipla1/bitwaveascend/tree/main/backend/include/core"
click node_game_manager "https://github.com/kipla1/bitwaveascend/blob/main/backend/include/core/GameManager.h"
click node_fighting "https://github.com/kipla1/bitwaveascend/blob/main/backend/include/gameplay/FightingMode.h"
click node_running "https://github.com/kipla1/bitwaveascend/blob/main/backend/include/gameplay/RunningMode.h"
click node_flappy "https://github.com/kipla1/bitwaveascend/blob/main/backend/include/gameplay/FlappyMode.h"
click node_gameplay_systems "https://github.com/kipla1/bitwaveascend/tree/main/backend/include/gameplay"
click node_entities "https://github.com/kipla1/bitwaveascend/tree/main/backend/include/entities"
click node_auth "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/auth/AuthServiceImpl.cpp"
click node_session "https://github.com/kipla1/bitwaveascend/blob/main/backend/include/auth/Session.h"
click node_alias "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/auth/AliasServiceImpl.cpp"
click node_profile "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/player/PlayerProfileServiceImpl.cpp"
click node_payment "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/PaymentServiceImpl.cpp"
click node_store "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/StoreImpl.cpp"
click node_wallet "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/WalletImpl.cpp"
click node_inventory "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/player/Inventory.cpp"
click node_database "https://github.com/kipla1/bitwaveascend/blob/main/backend/src/persistence/Database.cpp"
click node_repositories "https://github.com/kipla1/bitwaveascend/tree/main/backend/src/persistence"

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_frontend,node_contract,node_api,node_api_impl toneBlue
class node_game_core,node_game_manager,node_fighting,node_running,node_flappy,node_gameplay_systems,node_entities toneAmber
class node_auth,node_session,node_alias,node_profile toneMint
class node_payment,node_store,node_wallet,node_inventory toneRose
class node_database,node_repositories,node_player toneIndigo
```

## Components

### App boundary

- [SFML frontend](https://github.com/kipla1/bitwaveascend/blob/main/frontend/src/main.cpp): `frontend/src/main.cpp`
- [Shared contracts](https://github.com/kipla1/bitwaveascend/blob/main/shared/include/shared/Contracts.h): `shared/include/shared/Contracts.h`
- [Game API](https://github.com/kipla1/bitwaveascend/blob/main/shared/include/shared/GameAPI.h): `shared/include/shared/GameAPI.h`
- [Game API implementation](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/core/GameAPIImpl.cpp): `backend/src/core/GameAPIImpl.cpp`

### Game systems

- [Game core](https://github.com/kipla1/bitwaveascend/tree/main/backend/include/core): `backend/include/core`
- [Game manager](https://github.com/kipla1/bitwaveascend/blob/main/backend/include/core/GameManager.h): `backend/include/core/GameManager.h`
- [Fighting mode](https://github.com/kipla1/bitwaveascend/blob/main/backend/include/gameplay/FightingMode.h): `backend/include/gameplay/FightingMode.h`
- [Endless runner](https://github.com/kipla1/bitwaveascend/blob/main/backend/include/gameplay/RunningMode.h): `backend/include/gameplay/RunningMode.h`
- [Flappy mode](https://github.com/kipla1/bitwaveascend/blob/main/backend/include/gameplay/FlappyMode.h): `backend/include/gameplay/FlappyMode.h`
- [Gameplay systems](https://github.com/kipla1/bitwaveascend/tree/main/backend/include/gameplay): `backend/include/gameplay`
- [Game entities](https://github.com/kipla1/bitwaveascend/tree/main/backend/include/entities): `backend/include/entities`

### Identity and progression

- [Authentication](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/auth/AuthServiceImpl.cpp): `backend/src/auth/AuthServiceImpl.cpp`
- [Login session](https://github.com/kipla1/bitwaveascend/blob/main/backend/include/auth/Session.h): `backend/include/auth/Session.h`
- [Alias service](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/auth/AliasServiceImpl.cpp): `backend/src/auth/AliasServiceImpl.cpp`
- [Player profile](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/player/PlayerProfileServiceImpl.cpp): `backend/src/player/PlayerProfileServiceImpl.cpp`

### Virtual economy

- [Purchase service](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/PaymentServiceImpl.cpp): `backend/src/payment/PaymentServiceImpl.cpp`
- [Store](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/StoreImpl.cpp): `backend/src/payment/StoreImpl.cpp`
- [Wallet](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/payment/WalletImpl.cpp): `backend/src/payment/WalletImpl.cpp`
- [Inventory](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/player/Inventory.cpp): `backend/src/player/Inventory.cpp`

### Persistence

- [SQLite database](https://github.com/kipla1/bitwaveascend/blob/main/backend/src/persistence/Database.cpp): `backend/src/persistence/Database.cpp`
- [Data repositories](https://github.com/kipla1/bitwaveascend/tree/main/backend/src/persistence): `backend/src/persistence`

### Other components

- **Player**

## Connections

- Player → SFML frontend: interacts with (evidence: `README.md`)
- SFML frontend → Game API: uses (evidence: `README.md`)
- Game API → Shared contracts: shares types (evidence: `shared/include/shared/GameAPI.h`)
- Game API → Game API implementation: implemented by
- Game API implementation → Game core: dispatches to
- Game core → Game manager: manages
- Game manager → Fighting mode: selects mode
- Game manager → Endless runner: selects mode
- Game manager → Flappy mode: selects mode
- Game core → Gameplay systems: uses systems
- Gameplay systems → Game entities: updates entities
- Game API implementation → Authentication: handles account flow
- Authentication → Login session: starts or ends (evidence: `backend/src/auth/AuthServiceImpl.cpp`)
- Authentication → Data repositories: creates and looks up (evidence: `backend/src/auth/AuthServiceImpl.cpp`)
- Alias service → Data repositories: updates aliases
- Game API implementation → Player profile: reports progression
- Player profile → Data repositories: reads and updates
- Game API implementation → Purchase service: handles purchases
- Purchase service → Store: uses
- Purchase service → Wallet: uses
- Purchase service → Inventory: uses
- Purchase service → Data repositories: records transactions
- Data repositories → SQLite database: persists through