# lost-msth/arcaea-server architecture

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

- Interactive diagram: https://gitdiagram.com/lost-msth/arcaea-server
- Repository: https://github.com/lost-msth/arcaea-server

## Overview

#### Purpose and Runtime

Arcaea-server is a Python/Flask local server that emulates major Arcaea game backend functions: accounts, progression, scores/rankings, purchases, content delivery, cloud saves, and multiplayer. The primary HTTP application entry point is `latest version/main.py`; Link Play runs as a separate UDP-oriented process via `latest version/run_linkplay_server.py` and `latest version/linkplay_server/main.py`.

#### HTTP API Surface

Game-client endpoints are divided by domain under `latest version/api/`, including authentication, tokens, users, scores/songs, purchases, presents, redeems, and multiplayer:
- `latest version/api/api_auth.py`
- `latest version/api/users.py`
- `latest version/api/songs.py`

These handlers are the protocol boundary: they parse client requests, apply authentication/rate-limit/error conventions, and delegate game behavior to `core`.

#### Domain-Service Layer

`latest version/core/` is the business and persistence orchestration layer. It implements player state and game systems rather than exposing routes directly:
- Identity, authentication, and account state: `latest version/core/user.py`, `latest version/core/api_user.py`
- Scores, rankings, and potential calculations: `latest version/core/score.py`, `latest version/core/rank.py`
- Progression systems: `latest version/core/world.py`, `latest version/core/mission.py`, `latest version/core/course.py`
- Entitlements/content systems: `latest version/core/purchase.py`, `latest version/core/present.py`, `latest version/core/redeem.py`

API requests generally flow API module → core domain operation → SQL/data files → serialized game response.

#### Persistence and Initialization

SQLite-oriented persistence is centralized behind `latest version/core/sql.py`, while save serialization and initialization are handled by:
- `latest version/core/save.py`
- `latest version/core/init.py`
- `latest version/database/database_initialize.py`

Schema and baseline game data live in `latest version/database/init/tables.sql`, `latest version/database/init/arc_data.py`, and JSON datasets such as `latest version/database/init/courses.json`. This is a critical boundary: operational user data must be preserved across version updates, while schemas/static catalog data can be refreshed.

#### Static Game Catalog and Bundles

Game metadata and progression content are file-backed. World maps are JSON resources in `latest version/database/map/`; song/chart assets are expected under `latest version/database/songs/`. Bundle acquisition and delivery are represented by:
- `latest version/core/bundle.py`
- `latest version/core/download.py`
- `latest version/database/bundle/README.md`

The server can advertise or serve content updates, but the repository explicitly relies on external song/database sources and no longer distributes full song data.

#### Link Play / Multiplayer Boundary

Normal multiplayer API behavior is represented in `latest version/api/multiplay.py` and `latest version/core/linkplay.py`. Real-time Link Play is separately implemented as a UDP service with encryption, parsing, room/state storage, and outbound packet handling:
- `latest version/linkplay_server/main.py`
- `latest version/linkplay_server/udp_parser.py`
- `latest version/linkplay_server/store.py`

This service depends on Cryptography and should be deployed/configured alongside, but independently from, Flask.

#### Administration and Operations

A legacy server-rendered admin interface is separate from game APIs, with routes in `latest version/web/` and Jinja templates in `latest version/templates/web/`; its main purpose is inspecting/modifying users, scores, catalog items, purchases, presents, and database state. Cross-cutting operational controls include configuration, background tasks, logging, and request throttling:
- `latest version/core/config_manager.py`
- `latest version/core/bgtask.py`
- `latest version/core/limiter.py`

Material runtime dependencies are Python 3.6+, Flask, Cryptography, and limits, declared in `latest version/requirements.txt`.

Main entry points: [`latest version/main.py`](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/main.py) (Flask entry point), [`latest version/core/save.py`](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/save.py) (Save lifecycle), [`latest version/api/api_auth.py`](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/api_auth.py) (Game API modules), [`latest version/api/songs.py`](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/songs.py) (Songs & scores API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP Server"]
  node_flask["Flask entry point<br/>Python app<br/>[main.py]"]
  node_api["Game API modules<br/>Flask handlers<br/>[api_auth.py]"]
  node_users_api["Users API<br/>Flask handlers<br/>[users.py]"]
  node_songs_api["Songs &amp; scores API<br/>Flask handlers<br/>[songs.py]"]
  node_multiplay_api["Multiplayer API<br/>Flask handlers<br/>[multiplay.py]"]
end

subgraph group_core["Game Core"]
  node_domain["Account &amp; player state<br/>domain services<br/>[user.py]"]
  node_gameplay["Scores &amp; progression<br/>domain services<br/>[score.py]"]
  node_entitlements["Purchases &amp; rewards<br/>domain services<br/>[purchase.py]"]
  node_saves["Save lifecycle<br/>serialization<br/>[save.py]"]
  node_sql[("SQLite access<br/>persistence layer<br/>[sql.py]")]
  node_content["Bundles &amp; downloads<br/>content services<br/>[download.py]"]
end

subgraph group_data["Data &amp; Content"]
  node_database[("User database<br/>SQLite data")]
  node_schema["Schema &amp; seed data<br/>SQL and catalog data<br/>[tables.sql]"]
  node_catalog["Maps, songs &amp; bundles<br/>file-backed content"]
end

subgraph group_linkplay["Link Play"]
  node_linkplay_runtime["UDP Link Play runtime<br/>Python UDP service"]
  node_linkplay_protocol["Encrypted packet handling<br/>UDP protocol<br/>[udp_parser.py]"]
end

subgraph group_ops["Operations"]
  node_admin["Admin web interface<br/>server-rendered routes"]
  node_controls["Runtime controls<br/>cross-cutting services<br/>[config_manager.py]"]
end

node_flask -->|"serves"| node_api
node_flask -->|"serves"| node_users_api
node_flask -->|"serves"| node_songs_api
node_flask -->|"serves"| node_multiplay_api
node_flask -->|"uses"| node_controls
node_api -->|"auth &amp; accounts"| node_domain
node_users_api -->|"player operations"| node_domain
node_songs_api -->|"scores &amp; progression"| node_gameplay
node_api -->|"commerce &amp; rewards"| node_entitlements
node_domain -->|"loads and saves"| node_saves
node_gameplay -->|"updates state"| node_saves
node_entitlements -->|"grants state"| node_saves
node_saves -->|"persists through"| node_sql
node_sql -->|"reads and writes"| node_database
node_database -.->|"initialized from"| node_schema
node_songs_api -->|"content delivery"| node_content
node_content -->|"serves catalog assets"| node_catalog
node_multiplay_api -.->|"multiplayer state"| node_linkplay_protocol
node_linkplay_runtime -->|"runs"| node_linkplay_protocol
node_admin -->|"inspects and modifies"| node_sql
node_admin -->|"uses"| node_controls

click node_flask "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/main.py"
click node_api "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/api_auth.py"
click node_users_api "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/users.py"
click node_songs_api "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/songs.py"
click node_multiplay_api "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/multiplay.py"
click node_domain "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/user.py"
click node_gameplay "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/score.py"
click node_entitlements "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/purchase.py"
click node_saves "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/save.py"
click node_sql "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/sql.py"
click node_content "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/download.py"
click node_database "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/database/database_initialize.py"
click node_schema "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/database/init/tables.sql"
click node_linkplay_runtime "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/run_linkplay_server.py"
click node_linkplay_protocol "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/linkplay_server/udp_parser.py"
click node_controls "https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/config_manager.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_flask,node_api,node_users_api,node_songs_api,node_multiplay_api toneBlue
class node_domain,node_gameplay,node_entitlements,node_saves,node_sql,node_content toneAmber
class node_database,node_schema,node_catalog toneMint
class node_linkplay_runtime,node_linkplay_protocol toneRose
class node_admin,node_controls toneIndigo
```

## Components

### HTTP Server

- [Flask entry point](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/main.py): Python app · Primary game-client HTTP runtime. · `latest version/main.py`
- [Game API modules](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/api_auth.py): Flask handlers · Authenticated client protocol endpoints. · `latest version/api/api_auth.py`
- [Users API](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/users.py): Flask handlers · `latest version/api/users.py`
- [Songs & scores API](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/songs.py): Flask handlers · `latest version/api/songs.py`
- [Multiplayer API](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/api/multiplay.py): Flask handlers · `latest version/api/multiplay.py`

### Game Core

- [Account & player state](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/user.py): domain services · Identity, authentication, and account state operations. · `latest version/core/user.py`
- [Scores & progression](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/score.py): domain services · Rankings, potential, world, mission, and course systems. · `latest version/core/score.py`
- [Purchases & rewards](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/purchase.py): domain services · Purchase, present, and redeem operations. · `latest version/core/purchase.py`
- [Save lifecycle](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/save.py): serialization · Initializes and serializes player saves. · `latest version/core/save.py`
- [SQLite access](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/sql.py): persistence layer · Central SQL-oriented persistence boundary. · `latest version/core/sql.py`
- [Bundles & downloads](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/download.py): content services · Advertises and delivers content updates. · `latest version/core/download.py`

### Data & Content

- [User database](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/database/database_initialize.py): SQLite data · Operational player data preserved across updates. · `latest version/database/database_initialize.py`
- [Schema & seed data](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/database/init/tables.sql): SQL and catalog data · Refreshable schema and baseline game data. · `latest version/database/init/tables.sql`
- **Maps, songs & bundles**: file-backed content · Maps and external song assets; full song data is not distributed.

### Link Play

- [UDP Link Play runtime](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/run_linkplay_server.py): Python UDP service · Independent real-time multiplayer process. · `latest version/run_linkplay_server.py`
- [Encrypted packet handling](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/linkplay_server/udp_parser.py): UDP protocol · Parses packets and maintains room state. · `latest version/linkplay_server/udp_parser.py`

### Operations

- **Admin web interface**: server-rendered routes · Legacy inspection and modification interface.
- [Runtime controls](https://github.com/lost-msth/arcaea-server/blob/master/latest%20version/core/config_manager.py): cross-cutting services · Configuration, background tasks, logging, and rate limiting. · `latest version/core/config_manager.py`

## Connections

- Flask entry point → Game API modules: serves
- Flask entry point → Users API: serves
- Flask entry point → Songs & scores API: serves
- Flask entry point → Multiplayer API: serves
- Flask entry point → Runtime controls: uses
- Game API modules → Account & player state: auth & accounts
- Users API → Account & player state: player operations
- Songs & scores API → Scores & progression: scores & progression
- Game API modules → Purchases & rewards: commerce & rewards
- Account & player state → Save lifecycle: loads and saves
- Scores & progression → Save lifecycle: updates state
- Purchases & rewards → Save lifecycle: grants state
- Save lifecycle → SQLite access: persists through
- SQLite access → User database: reads and writes
- User database → Schema & seed data: initialized from
- Songs & scores API → Bundles & downloads: content delivery
- Bundles & downloads → Maps, songs & bundles: serves catalog assets
- Multiplayer API → Encrypted packet handling: multiplayer state
- UDP Link Play runtime → Encrypted packet handling: runs
- Admin web interface → SQLite access: inspects and modifies
- Admin web interface → Runtime controls: uses
