# seriaati/genshin.py architecture

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

- Interactive diagram: https://gitdiagram.com/seriaati/genshin.py
- Repository: https://github.com/seriaati/genshin.py

## Overview

genshin.py is an asyncio and Pydantic wrapper for HoYoLAB and game APIs. A caller creates a Client, optionally authenticates or supplies cookies, then invokes a domain method; the client makes routed requests and returns parsed models. The graph preserves the documented multi-game chronicle, HoYoLAB, calculator, and other endpoint families. Several component implementations are unsampled, so their internal call paths are omitted; edges rely on README statements or relationships visible in the supplied excerpts and source index.

Main entry points: [`genshin/client/clients.py`](https://github.com/seriaati/genshin.py/blob/master/genshin/client/clients.py) (Client facade), [`genshin/client/components/base.py`](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/base.py) (Request client), [`genshin/client/components/auth/client.py`](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/client.py) (Auth workflows), [`genshin/client/components/chronicle/genshin.py`](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/chronicle/genshin.py) (Game chronicles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client runtime"]
  node_client["Client facade<br/>[clients.py]"]
  node_base["Request client<br/>[base.py]"]
  node_cache["Response cache<br/>[cache.py]"]
  node_manager["Cookie managers<br/>[managers.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_paginators["API pagination<br/>[api.py]"]
end

subgraph group_auth["Authentication"]
  node_auth_client["Auth workflows<br/>[client.py]"]
  node_auth_app["App login<br/>[app.py]"]
  node_captcha["Captcha server<br/>[server.py]"]
  node_auth_utils["Auth utilities<br/>[auth.py]"]
end

subgraph group_domains["API capabilities"]
  node_hoyo["HoYoLAB APIs<br/>[hoyolab.py]"]
  node_chronicle["Game chronicles<br/>[genshin.py]"]
  node_chronicle_base["Chronicle base<br/>[base.py]"]
  node_daily["Daily rewards<br/>[daily.py]"]
  node_diary["Spending diary<br/>[diary.py]"]
  node_gacha["Gacha records<br/>[gacha.py]"]
  node_calculator["Enhancement calculator<br/>[client.py]"]
end

subgraph group_models["Response models"]
  node_models["Game and account models"]
  node_model_base["Pydantic model base<br/>[model.py]"]
end

node_caller(("Library caller"))
node_hoyolab_service{{"HoYoLAB API"}}
node_game_service{{"Game APIs"}}

node_caller -->|"creates and calls"| node_client
node_client -->|"exposes"| node_hoyo
node_client -->|"exposes"| node_chronicle
node_client -->|"exposes"| node_daily
node_client -->|"exposes"| node_diary
node_client -->|"exposes"| node_gacha
node_client -->|"exposes"| node_calculator
node_client -->|"exposes"| node_auth_client
node_base -->|"reads and writes"| node_cache
node_base -->|"uses endpoints"| node_routes
node_base -->|"uses cookies"| node_manager
node_manager -->|"sends requests"| node_hoyolab_service
node_routes -->|"defines endpoints"| node_hoyolab_service
node_routes -->|"defines endpoints"| node_game_service
node_hoyo -->|"uses request client"| node_base
node_chronicle -->|"inherits from"| node_chronicle_base
node_chronicle -->|"builds responses"| node_models
node_chronicle -->|"uses pagination"| node_paginators
node_calculator -->|"uses request client"| node_base
node_calculator -->|"builds responses"| node_models
node_auth_client -->|"dispatches login"| node_auth_app
node_auth_client -->|"solves challenges"| node_captcha
node_auth_client -->|"uses cookie manager"| node_manager
node_auth_app -->|"sends login requests"| node_manager
node_auth_app -->|"signs requests"| node_auth_utils
node_models -->|"uses base model"| node_model_base

click node_client "https://github.com/seriaati/genshin.py/blob/master/genshin/client/clients.py"
click node_base "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/base.py"
click node_cache "https://github.com/seriaati/genshin.py/blob/master/genshin/client/cache.py"
click node_manager "https://github.com/seriaati/genshin.py/blob/master/genshin/client/manager/managers.py"
click node_routes "https://github.com/seriaati/genshin.py/blob/master/genshin/client/routes.py"
click node_hoyo "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/hoyolab.py"
click node_chronicle "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/chronicle/genshin.py"
click node_chronicle_base "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/chronicle/base.py"
click node_daily "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/daily.py"
click node_diary "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/diary.py"
click node_gacha "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/gacha.py"
click node_calculator "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/calculator/client.py"
click node_auth_client "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/client.py"
click node_auth_app "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/subclients/app.py"
click node_captcha "https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/server.py"
click node_auth_utils "https://github.com/seriaati/genshin.py/blob/master/genshin/utility/auth.py"
click node_models "https://github.com/seriaati/genshin.py/tree/master/genshin/models"
click node_model_base "https://github.com/seriaati/genshin.py/blob/master/genshin/models/model.py"
click node_paginators "https://github.com/seriaati/genshin.py/blob/master/genshin/paginators/api.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_client,node_base,node_cache,node_manager,node_routes,node_paginators toneBlue
class node_auth_client,node_auth_app,node_captcha,node_auth_utils toneAmber
class node_hoyo,node_chronicle,node_chronicle_base,node_daily,node_diary,node_gacha,node_calculator,node_hoyolab_service,node_game_service toneMint
class node_models,node_model_base toneRose
class node_caller toneIndigo
```

## Components

### Client runtime

- [Client facade](https://github.com/seriaati/genshin.py/blob/master/genshin/client/clients.py): `genshin/client/clients.py`
- [Request client](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/base.py): `genshin/client/components/base.py`
- [Response cache](https://github.com/seriaati/genshin.py/blob/master/genshin/client/cache.py): `genshin/client/cache.py`
- [Cookie managers](https://github.com/seriaati/genshin.py/blob/master/genshin/client/manager/managers.py): `genshin/client/manager/managers.py`
- [API routes](https://github.com/seriaati/genshin.py/blob/master/genshin/client/routes.py): `genshin/client/routes.py`
- [API pagination](https://github.com/seriaati/genshin.py/blob/master/genshin/paginators/api.py): `genshin/paginators/api.py`

### Authentication

- [Auth workflows](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/client.py): `genshin/client/components/auth/client.py`
- [App login](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/subclients/app.py): `genshin/client/components/auth/subclients/app.py`
- [Captcha server](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/auth/server.py): `genshin/client/components/auth/server.py`
- [Auth utilities](https://github.com/seriaati/genshin.py/blob/master/genshin/utility/auth.py): `genshin/utility/auth.py`

### API capabilities

- [HoYoLAB APIs](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/hoyolab.py): `genshin/client/components/hoyolab.py`
- [Game chronicles](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/chronicle/genshin.py): `genshin/client/components/chronicle/genshin.py`
- [Chronicle base](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/chronicle/base.py): `genshin/client/components/chronicle/base.py`
- [Daily rewards](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/daily.py): `genshin/client/components/daily.py`
- [Spending diary](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/diary.py): `genshin/client/components/diary.py`
- [Gacha records](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/gacha.py): `genshin/client/components/gacha.py`
- [Enhancement calculator](https://github.com/seriaati/genshin.py/blob/master/genshin/client/components/calculator/client.py): `genshin/client/components/calculator/client.py`

### Response models

- [Game and account models](https://github.com/seriaati/genshin.py/tree/master/genshin/models): `genshin/models`
- [Pydantic model base](https://github.com/seriaati/genshin.py/blob/master/genshin/models/model.py): `genshin/models/model.py`

### Other components

- **Library caller**
- **HoYoLAB API**
- **Game APIs**

## Connections

- Library caller → Client facade: creates and calls
- Client facade → HoYoLAB APIs: exposes (evidence: `genshin/client/clients.py`)
- Client facade → Game chronicles: exposes (evidence: `genshin/client/clients.py`)
- Client facade → Daily rewards: exposes (evidence: `genshin/client/clients.py`)
- Client facade → Spending diary: exposes (evidence: `genshin/client/clients.py`)
- Client facade → Gacha records: exposes (evidence: `genshin/client/clients.py`)
- Client facade → Enhancement calculator: exposes (evidence: `genshin/client/clients.py`)
- Client facade → Auth workflows: exposes (evidence: `genshin/client/clients.py`)
- Request client → Response cache: reads and writes (evidence: `genshin/client/components/base.py`)
- Request client → API routes: uses endpoints (evidence: `genshin/client/components/base.py`)
- Request client → Cookie managers: uses cookies (evidence: `genshin/client/components/base.py`)
- Cookie managers → HoYoLAB API: sends requests (evidence: `genshin/client/manager/managers.py`)
- API routes → HoYoLAB API: defines endpoints (evidence: `genshin/client/routes.py`)
- API routes → Game APIs: defines endpoints (evidence: `genshin/client/routes.py`)
- HoYoLAB APIs → Request client: uses request client (evidence: `genshin/client/components/hoyolab.py`)
- Game chronicles → Chronicle base: inherits from (evidence: `genshin/client/components/chronicle/genshin.py`)
- Game chronicles → Game and account models: builds responses (evidence: `genshin/client/components/chronicle/genshin.py`)
- Game chronicles → API pagination: uses pagination (evidence: `genshin/client/components/chronicle/genshin.py`)
- Enhancement calculator → Request client: uses request client (evidence: `genshin/client/components/calculator/client.py`)
- Enhancement calculator → Game and account models: builds responses (evidence: `genshin/client/components/calculator/client.py`)
- Auth workflows → App login: dispatches login (evidence: `genshin/client/components/auth/client.py`)
- Auth workflows → Captcha server: solves challenges (evidence: `genshin/client/components/auth/client.py`)
- Auth workflows → Cookie managers: uses cookie manager (evidence: `genshin/client/components/auth/client.py`)
- App login → Cookie managers: sends login requests (evidence: `genshin/client/components/auth/subclients/app.py`)
- App login → Auth utilities: signs requests (evidence: `genshin/client/components/auth/subclients/app.py`)
- Game and account models → Pydantic model base: uses base model (evidence: `genshin/models/genshin/calculator.py`)