# duynguyen658/gamedefi architecture

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

- Interactive diagram: https://gitdiagram.com/duynguyen658/gamedefi
- Repository: https://github.com/duynguyen658/gamedefi

## Overview

Hào Khí Đại Việt is a history-themed strategy GameFi: players enter as guests or authenticate with a wallet, choose a faction, prepare an army, select a historical campaign battle, and can use advisor, marketplace, reward, and DEX features. The frontend excerpts show the app-level navigation and wallet/faction hooks; backend route wiring and battle calculation are sampled, but most individual routes and integrations are not, so uncertain internal calls are omitted.

Main entry points: [`vietnam-history-gamefi/backend/app/main.py`](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/main.py) (FastAPI application), [`vietnam-history-gamefi/frontend/src/App.tsx`](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/App.tsx) (App navigation), [`vietnam-history-gamefi/frontend/src/services/api.ts`](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/services/api.ts) (API client), [`vietnam-history-gamefi/backend/app/dex`](https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/backend/app/dex) (DEX providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game client"]
  node_app["App navigation<br/>[App.tsx]"]
  node_game_views["Game screens"]
  node_wallet_hook["Wallet session<br/>[useWallet.ts]"]
  node_faction_hook["Faction selection<br/>[useFaction.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_gameplay["Gameplay services"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth["Wallet and guest auth<br/>[auth.py]"]
  node_battle_routes["Battle routes<br/>[battle.py]"]
  node_battle_engine["Battle simulation<br/>[battle_engine.py]"]
  node_other_game_routes["Game feature routes"]
  node_reward_routes["Reward claims<br/>[reward.py]"]
end

subgraph group_chain["Blockchain and DeFi"]
  node_chain_routes["Blockchain routes<br/>[blockchain.py]"]
  node_dex_routes["DEX routes<br/>[dex.py]"]
  node_adapter["Solana adapter<br/>[solana_adapter.py]"]
  node_solana_program["Solana game program<br/>[lib.rs]"]
  node_dex_providers["DEX providers"]
end

subgraph group_state["State and persistence"]
  node_store["Gameplay state<br/>[store.py]"]
  node_reward_repo["Reward persistence<br/>[persistence.py]"]
  node_dex_repo[("DEX persistence<br/>[persistence.py]")]
end

node_player(("Player"))
node_db[("Configured database")]
node_solana_network(("Solana network"))
node_dex_networks(("DEX networks"))

node_player -->|"uses"| node_app
node_app -->|"renders"| node_game_views
node_app -->|"uses"| node_wallet_hook
node_app -->|"uses"| node_faction_hook
node_wallet_hook -->|"requests auth"| node_api_client
node_faction_hook -->|"loads and registers"| node_api_client
node_api_client -->|"sends API requests"| node_backend
node_backend -->|"mounts"| node_auth
node_backend -->|"mounts"| node_battle_routes
node_backend -->|"mounts"| node_other_game_routes
node_backend -->|"mounts"| node_reward_routes
node_backend -->|"mounts"| node_chain_routes
node_backend -->|"mounts"| node_dex_routes
node_auth -->|"creates players"| node_store
node_battle_engine -->|"reads and records"| node_store
node_reward_routes -->|"persists claims"| node_reward_repo
node_reward_repo -->|"reads and writes"| node_db
node_backend -->|"initializes"| node_dex_repo
node_dex_repo -->|"reads and writes"| node_db
node_backend -->|"creates provider"| node_dex_providers
node_dex_routes -->|"uses provider"| node_dex_providers
node_dex_providers -.->|"trades against"| node_dex_networks
node_chain_routes -->|"resolves adapter"| node_adapter
node_adapter -->|"submits transactions"| node_solana_network
node_solana_program -.->|"deployed on"| node_solana_network

click node_app "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/App.tsx"
click node_game_views "https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/frontend/src/components"
click node_wallet_hook "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/hooks/useWallet.ts"
click node_faction_hook "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/hooks/useFaction.ts"
click node_api_client "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/services/api.ts"
click node_backend "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/main.py"
click node_auth "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/auth.py"
click node_battle_routes "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/battle.py"
click node_battle_engine "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/domain/battle_engine.py"
click node_other_game_routes "https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/backend/app/api"
click node_reward_routes "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/reward.py"
click node_chain_routes "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/blockchain.py"
click node_dex_routes "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/dex.py"
click node_adapter "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/blockchain/solana_adapter.py"
click node_solana_program "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/blockchain/solana/programs/history_game/src/lib.rs"
click node_dex_providers "https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/backend/app/dex"
click node_store "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/core/store.py"
click node_reward_repo "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/rewards/persistence.py"
click node_dex_repo "https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/dex/persistence.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_app,node_game_views,node_wallet_hook,node_faction_hook,node_api_client toneBlue
class node_backend,node_auth,node_battle_routes,node_battle_engine,node_other_game_routes,node_reward_routes,node_db toneAmber
class node_chain_routes,node_dex_routes,node_adapter,node_solana_program,node_dex_providers toneMint
class node_store,node_reward_repo,node_dex_repo toneRose
class node_player,node_solana_network,node_dex_networks toneIndigo
```

## Components

### Game client

- [App navigation](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/App.tsx): `vietnam-history-gamefi/frontend/src/App.tsx`
- [Game screens](https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/frontend/src/components): `vietnam-history-gamefi/frontend/src/components`
- [Wallet session](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/hooks/useWallet.ts): `vietnam-history-gamefi/frontend/src/hooks/useWallet.ts`
- [Faction selection](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/hooks/useFaction.ts): `vietnam-history-gamefi/frontend/src/hooks/useFaction.ts`
- [API client](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/frontend/src/services/api.ts): `vietnam-history-gamefi/frontend/src/services/api.ts`

### Gameplay services

- [FastAPI application](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/main.py): `vietnam-history-gamefi/backend/app/main.py`
- [Wallet and guest auth](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/auth.py): `vietnam-history-gamefi/backend/app/api/auth.py`
- [Battle routes](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/battle.py): `vietnam-history-gamefi/backend/app/api/battle.py`
- [Battle simulation](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/domain/battle_engine.py): `vietnam-history-gamefi/backend/app/domain/battle_engine.py`
- [Game feature routes](https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/backend/app/api): `vietnam-history-gamefi/backend/app/api`
- [Reward claims](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/reward.py): `vietnam-history-gamefi/backend/app/api/reward.py`

### Blockchain and DeFi

- [Blockchain routes](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/blockchain.py): `vietnam-history-gamefi/backend/app/api/blockchain.py`
- [DEX routes](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/api/dex.py): `vietnam-history-gamefi/backend/app/api/dex.py`
- [Solana adapter](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/blockchain/solana_adapter.py): `vietnam-history-gamefi/backend/app/blockchain/solana_adapter.py`
- [Solana game program](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/blockchain/solana/programs/history_game/src/lib.rs): `vietnam-history-gamefi/blockchain/solana/programs/history_game/src/lib.rs`
- [DEX providers](https://github.com/duynguyen658/gamedefi/tree/main/vietnam-history-gamefi/backend/app/dex): `vietnam-history-gamefi/backend/app/dex`

### State and persistence

- [Gameplay state](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/core/store.py): `vietnam-history-gamefi/backend/app/core/store.py`
- [Reward persistence](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/rewards/persistence.py): `vietnam-history-gamefi/backend/app/rewards/persistence.py`
- [DEX persistence](https://github.com/duynguyen658/gamedefi/blob/main/vietnam-history-gamefi/backend/app/dex/persistence.py): `vietnam-history-gamefi/backend/app/dex/persistence.py`

### Other components

- **Player**
- **Configured database**
- **Solana network**
- **DEX networks**

## Connections

- Player → App navigation: uses
- App navigation → Game screens: renders
- App navigation → Wallet session: uses
- App navigation → Faction selection: uses
- Wallet session → API client: requests auth
- Faction selection → API client: loads and registers
- API client → FastAPI application: sends API requests
- FastAPI application → Wallet and guest auth: mounts
- FastAPI application → Battle routes: mounts
- FastAPI application → Game feature routes: mounts
- FastAPI application → Reward claims: mounts
- FastAPI application → Blockchain routes: mounts
- FastAPI application → DEX routes: mounts
- Wallet and guest auth → Gameplay state: creates players
- Battle simulation → Gameplay state: reads and records
- Reward claims → Reward persistence: persists claims
- Reward persistence → Configured database: reads and writes
- FastAPI application → DEX persistence: initializes
- DEX persistence → Configured database: reads and writes
- FastAPI application → DEX providers: creates provider
- DEX routes → DEX providers: uses provider
- DEX providers → DEX networks: trades against
- Blockchain routes → Solana adapter: resolves adapter
- Solana adapter → Solana network: submits transactions
- Solana game program → Solana network: deployed on