# almarch/pygotchi architecture

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

- Interactive diagram: https://gitdiagram.com/almarch/pygotchi
- Repository: https://github.com/almarch/pygotchi
- Video tour (about a minute): https://gitdiagram.com/almarch/pygotchi/video

## Overview

PyGotchi is a multi-user web service for running Tamagotchi ROMs in a server-side emulator, with a browser client and optional automatic care. The main workflow is: an authenticated user opens a game, uploads a ROM, starts and controls the emulation, receives live screen/audio/status updates, and can save or reload CPU state. The README also documents P1/P2 adaptation and secure deployment with Keycloak and Nginx. Runtime connections below follow the sampled app, emulator, care, and browser code; deployment wiring is included only where documented.

Main entry points: [`pygotchi/app.py`](https://github.com/almarch/pygotchi/blob/main/pygotchi/app.py) (Web API), [`pygotchi/Tama.py`](https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py) (Tama interface), [`pygotchi/www/script.js`](https://github.com/almarch/pygotchi/blob/main/pygotchi/www/script.js) (Game browser), [`nginx/nginx.conf`](https://github.com/almarch/pygotchi/blob/main/nginx/nginx.conf) (Reverse proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client and API"]
  node_browser["Game browser<br/>[script.js]"]
  node_assets["Game assets"]
  node_api["Web API<br/>[app.py]"]
  node_session["User game session<br/>[app.py]"]
end

subgraph group_game["Game runtime"]
  node_tama["Tama interface<br/>[Tama.py]"]
  node_worker["Emulator worker<br/>[Tama.py]"]
  node_core["TamaLIB core<br/>[tamalib.cpp]"]
  node_romcpu["ROM and CPU state<br/>[Tama.py]"]
  node_conversion["Binary conversion<br/>[conversion.py]"]
  node_p2["P2 conversion<br/>[p2.py]"]
end

subgraph group_care["Automatic care"]
  node_carebot["Carebot scheduler<br/>[Carebot.py]"]
  node_carelogic["P1/P2 care logic<br/>[care_p1p2.py]"]
end

subgraph group_deploy["Authentication edge"]
  node_nginx["Reverse proxy<br/>[nginx.conf]"]
  node_keycloak["Identity service<br/>[realm-game.json]"]
end

node_player(("Player"))

node_player -->|"uses game"| node_browser
node_browser -->|"sends actions"| node_api
node_api -->|"creates or selects"| node_session
node_session -->|"owns emulator"| node_tama
node_session -->|"starts care task"| node_carebot
node_browser -->|"loads artwork"| node_assets
node_api -->|"controls and queries"| node_tama
node_tama -->|"dispatches calls"| node_worker
node_worker -->|"calls emulator"| node_core
node_worker -->|"reads and updates"| node_romcpu
node_romcpu -->|"converts bytes"| node_conversion
node_api -->|"manages care"| node_carebot
node_carebot -->|"runs care steps"| node_carelogic
node_carelogic -->|"checks and acts"| node_tama
node_api -->|"requests conversion"| node_p2
node_p2 -->|"updates ROM"| node_tama
node_api -->|"streams screen audio status"| node_browser
node_player -.->|"accesses service"| node_nginx
node_nginx -.->|"proxies requests"| node_api
node_nginx -.->|"uses authentication"| node_keycloak

click node_browser "https://github.com/almarch/pygotchi/blob/main/pygotchi/www/script.js"
click node_assets "https://github.com/almarch/pygotchi/tree/main/pygotchi/www"
click node_api "https://github.com/almarch/pygotchi/blob/main/pygotchi/app.py"
click node_session "https://github.com/almarch/pygotchi/blob/main/pygotchi/app.py"
click node_tama "https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py"
click node_worker "https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py"
click node_core "https://github.com/almarch/pygotchi/blob/main/src/tamalib.cpp"
click node_romcpu "https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py"
click node_conversion "https://github.com/almarch/pygotchi/blob/main/pygotchi/conversion.py"
click node_carebot "https://github.com/almarch/pygotchi/blob/main/pygotchi/Carebot.py"
click node_carelogic "https://github.com/almarch/pygotchi/blob/main/pygotchi/care_p1p2.py"
click node_p2 "https://github.com/almarch/pygotchi/blob/main/pygotchi/p2.py"
click node_nginx "https://github.com/almarch/pygotchi/blob/main/nginx/nginx.conf"
click node_keycloak "https://github.com/almarch/pygotchi/blob/main/keycloak/realm-game.json"

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_browser,node_assets,node_api,node_session toneBlue
class node_tama,node_worker,node_core,node_romcpu,node_conversion,node_p2 toneAmber
class node_carebot,node_carelogic toneMint
class node_nginx,node_keycloak toneRose
class node_player toneIndigo
```

## Components

### Web client and API

- [Game browser](https://github.com/almarch/pygotchi/blob/main/pygotchi/www/script.js): `pygotchi/www/script.js`
- [Game assets](https://github.com/almarch/pygotchi/tree/main/pygotchi/www): `pygotchi/www`
- [Web API](https://github.com/almarch/pygotchi/blob/main/pygotchi/app.py): `pygotchi/app.py`
- [User game session](https://github.com/almarch/pygotchi/blob/main/pygotchi/app.py): `pygotchi/app.py`

### Game runtime

- [Tama interface](https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py): `pygotchi/Tama.py`
- [Emulator worker](https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py): `pygotchi/Tama.py`
- [TamaLIB core](https://github.com/almarch/pygotchi/blob/main/src/tamalib.cpp): `src/tamalib.cpp`
- [ROM and CPU state](https://github.com/almarch/pygotchi/blob/main/pygotchi/Tama.py): `pygotchi/Tama.py`
- [Binary conversion](https://github.com/almarch/pygotchi/blob/main/pygotchi/conversion.py): `pygotchi/conversion.py`
- [P2 conversion](https://github.com/almarch/pygotchi/blob/main/pygotchi/p2.py): `pygotchi/p2.py`

### Automatic care

- [Carebot scheduler](https://github.com/almarch/pygotchi/blob/main/pygotchi/Carebot.py): `pygotchi/Carebot.py`
- [P1/P2 care logic](https://github.com/almarch/pygotchi/blob/main/pygotchi/care_p1p2.py): `pygotchi/care_p1p2.py`

### Authentication edge

- [Reverse proxy](https://github.com/almarch/pygotchi/blob/main/nginx/nginx.conf): `nginx/nginx.conf`
- [Identity service](https://github.com/almarch/pygotchi/blob/main/keycloak/realm-game.json): `keycloak/realm-game.json`

### Other components

- **Player**

## Connections

- Player → Game browser: uses game
- Game browser → Web API: sends actions
- Web API → User game session: creates or selects
- User game session → Tama interface: owns emulator
- User game session → Carebot scheduler: starts care task
- Game browser → Game assets: loads artwork
- Web API → Tama interface: controls and queries
- Tama interface → Emulator worker: dispatches calls
- Emulator worker → TamaLIB core: calls emulator
- Emulator worker → ROM and CPU state: reads and updates
- ROM and CPU state → Binary conversion: converts bytes
- Web API → Carebot scheduler: manages care
- Carebot scheduler → P1/P2 care logic: runs care steps
- P1/P2 care logic → Tama interface: checks and acts
- Web API → P2 conversion: requests conversion
- P2 conversion → Tama interface: updates ROM
- Web API → Game browser: streams screen audio status
- Player → Reverse proxy: accesses service
- Reverse proxy → Web API: proxies requests
- Reverse proxy → Identity service: uses authentication