<!-- file: docs/studies/020-UROBURAS_CRATE_DECOMPOSITION_STUDY.md -->
<!-- version: 1 -->

# Uroburas — étude de décomposition en crates

## Statut

Étude non normative pour `0.2.0-0-pre.6`.

Les noms ci-dessous sont des candidats, pas encore des crates à créer immédiatement.

## Engine existant

À conserver comme fondation :

```text
crates/engines/engine-v1-common
crates/engines/engine-v1-platform-api
crates/engines/engine-v1-sdl
```

Le kernel ne doit pas absorber les systèmes de grille, score ou Snake uniquement parce que Uroburas en a besoin.

## Capabilities candidates

Famille possible :

```text
crates/capabilities/
    game-assets-lib
    game-input-lib
    game-localization-lib
    game-network-client-lib
    game-persistence-lib
    game-audio-lib
```

Les noms finaux devront respecter les règles workspace et éviter les crates artificiellement petites.

## Game-systems candidates

Famille possible :

```text
crates/game-systems/
    game-grid-lib
    game-collision-grid-lib
    game-stage-lib
    game-score-lib
    game-lives-lib
    game-timed-entity-lib
    game-pickup-lib
```

Ces crates ne sont créées que si leur API est suffisamment stable et réutilisable.

Des mécanismes très liés peuvent rester regroupés dans une même crate plutôt que multiplier les packages.

## Uroburas game crates

Proposition progressive :

```text
crates/games/
    game-uroburas-lib
```

Cette crate compose les règles Uroburas.

Si la complexité le justifie plus tard :

```text
game-uroburas-core-lib
game-uroburas-content-lib
game-uroburas-protocol-lib
```

Mais ne pas splitter avant besoin réel.

`game-uroburas-lib` ne doit pas dépendre directement de :

- Actix ;
- Maud ;
- Lettre ;
- tokio-tungstenite ;
- SDK publicitaire ;
- Java Android ;
- Tauri API.

## Applications client

Candidats futurs :

```text
crates/apps/
    game-uroburas-desktop
    game-uroburas-wasm
    game-uroburas-tauri
    game-uroburas-android-entrypoint
```

Les apps composent :

- jeu ;
- adapters plateforme ;
- capabilities ;
- providers nécessaires.

## Server crates

Famille proposée :

```text
crates/servers/
    uroburas-server-domain-lib
    uroburas-server-api-lib
    uroburas-server-web
    uroburas-server-realtime
```

Puis seulement si besoin :

```text
uroburas-server-media
uroburas-server-admin
```

### server-domain-lib

Contient des concepts serveur partagés :

- PlayerId ;
- MapId/MapVersion ;
- ScoreSubmission ;
- HallOfFameEntry ;
- RewardGrant ;
- Session identifiers.

Ne contient pas Actix/Tungstenite/Tonic.

### server-api-lib

Contrats DTO/protocole :

- HTTP DTOs ;
- WebSocket messages ;
- versioning ;
- validation structurale.

Les wire types restent distincts des modèles métier internes.

### server-web

- Actix Web ;
- Maud ;
- auth endpoints ;
- Hall of Fame ;
- maps/assets metadata ;
- administration initiale ;
- Fluent serveur ;
- Lettre.

### server-realtime

Future Mode 3/2 :

- Tokio ;
- tokio-tungstenite ;
- rooms/worlds ;
- authoritative simulation ;
- snapshots/deltas ;
- spectator ;
- bots.

## Providers

Famille possible :

```text
crates/providers/
    game-ads-api-lib
    game-ads-<provider>-lib
    game-auth-<provider>-lib
```

Ne pas créer les providers tant qu'ils ne sont pas nécessaires à une cible réelle.

## Tooling

Candidats futurs :

```text
crates/tools/
    uroburas-map-editor
    uroburas-skin-editor
```

Un éditeur Web peut aussi avoir sa propre app/host au lieu d'être une crate de jeu.

## Anti-monolithe

Avant d'ajouter une fonctionnalité à `game-uroburas-lib`, poser trois questions :

1. connaît-elle explicitement les règles Uroburas ?
2. serait-elle utile dans un autre jeu sans référence à Uroburas ?
3. dépend-elle d'une plateforme, d'un transport ou d'un provider ?

Si la réponse à 1 est non et à 2 ou 3 est oui, elle appartient probablement ailleurs.