# bua9595/pets architecture

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

- Interactive diagram: https://gitdiagram.com/bua9595/pets
- Repository: https://github.com/bua9595/pets

## Overview

Hatch Desktop Pet is a local multi-pet application with a Tk desktop runtime and a separate CLI hatch/interaction flow. Its principal runtime workflow loads a pet’s manifest and sprite atlas, selects animations in response to automatic behavior or user actions, and displays them in a movable desktop window. A second major capability is preparing and reviewing approved sprite sources, building per-pet atlases with QA outputs, and exporting Ruffy for Codex. Runtime and builder excerpts support the core links; some documented subsystems are represented at their existing directory paths because their source was not sampled.

Main entry points: [`src/main.py`](https://github.com/bua9595/pets/blob/main/src/main.py) (Hatch CLI), [`assets/pets`](https://github.com/bua9595/pets/tree/main/assets/pets) (Pet manifests and atlases), [`src/pet.py`](https://github.com/bua9595/pets/blob/main/src/pet.py) (Pet state and actions), [`src/hatch_flow.py`](https://github.com/bua9595/pets/blob/main/src/hatch_flow.py) (Hatch flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Pet runtime"]
  node_desktop["Desktop window<br/>[desktop_pet.py]"]
  node_animator["Sprite animator<br/>[sprite_animator.py]"]
  node_petdata[("Pet manifests and atlases")]
end

subgraph group_cli["CLI interactions"]
  node_cli["Hatch CLI<br/>[main.py]"]
  node_hatchflow["Hatch flow<br/>[hatch_flow.py]"]
  node_pet["Pet state and actions<br/>[pet.py]"]
  node_state["Pet state model<br/>[pet_state.py]"]
  node_actions["Action handler<br/>[actions.py]"]
  node_lookloader["Look and asset loader<br/>[asset_loader.py]"]
end

subgraph group_assets["Sprite assets"]
  node_approved[("Approved sprite sources")]
  node_review["Source review workflow"]
  node_ruffybuilder["Ruffy atlas builder"]
  node_chibibuilder["Chibi atlas builder"]
  node_qa["Sprite QA<br/>[sprite_qa.py]"]
end

subgraph group_integrations["Exports and skills"]
  node_skillloader["Skill loader<br/>[skill_loader.py]"]
  node_skills["Skill definitions<br/>[skills.py]"]
  node_codex["Codex pet export"]
  node_codexassets[("Codex pet package")]
  node_skillpackage["Hatch pet skill"]
end

node_user(("Pet owner"))

node_user -->|"starts or controls"| node_desktop
node_desktop -->|"plays animations"| node_animator
node_animator -->|"reads manifest and atlas"| node_petdata
node_user -->|"runs commands"| node_cli
node_cli -->|"loads look"| node_lookloader
node_cli -->|"starts hatch flow"| node_hatchflow
node_cli -->|"creates pet"| node_pet
node_cli -->|"dispatches action"| node_actions
node_hatchflow -->|"applies gear or skill"| node_pet
node_pet -->|"updates state"| node_state
node_actions -->|"performs action"| node_pet
node_skillloader -->|"loads skills"| node_skills
node_hatchflow -->|"loads skills"| node_skillloader
node_review -->|"approves sources"| node_approved
node_approved -->|"provides source sprites"| node_ruffybuilder
node_approved -->|"provides source sprites"| node_chibibuilder
node_ruffybuilder -->|"writes Ruffy atlas and manifest"| node_petdata
node_chibibuilder -->|"writes Chibi atlas and manifest"| node_petdata
node_ruffybuilder -->|"produces QA results"| node_qa
node_chibibuilder -->|"produces QA results"| node_qa
node_petdata -->|"supplies runtime atlas"| node_codex
node_codex -->|"writes pet package"| node_codexassets
node_skillpackage -.->|"guides asset creation"| node_user

click node_desktop "https://github.com/bua9595/pets/blob/main/src/desktop_pet.py"
click node_animator "https://github.com/bua9595/pets/blob/main/src/sprite_animator.py"
click node_petdata "https://github.com/bua9595/pets/tree/main/assets/pets"
click node_cli "https://github.com/bua9595/pets/blob/main/src/main.py"
click node_hatchflow "https://github.com/bua9595/pets/blob/main/src/hatch_flow.py"
click node_pet "https://github.com/bua9595/pets/blob/main/src/pet.py"
click node_state "https://github.com/bua9595/pets/blob/main/src/pet_state.py"
click node_actions "https://github.com/bua9595/pets/blob/main/src/actions.py"
click node_lookloader "https://github.com/bua9595/pets/blob/main/src/asset_loader.py"
click node_skillloader "https://github.com/bua9595/pets/blob/main/src/skill_loader.py"
click node_skills "https://github.com/bua9595/pets/blob/main/src/skills.py"
click node_approved "https://github.com/bua9595/pets/tree/main/assets/source_approved"
click node_review "https://github.com/bua9595/pets/tree/main/assets/review"
click node_ruffybuilder "https://github.com/bua9595/pets/blob/main/src/pet1_ruffy_builder.py"
click node_chibibuilder "https://github.com/bua9595/pets/blob/main/src/pet2_chibi_builder.py"
click node_qa "https://github.com/bua9595/pets/blob/main/src/sprite_qa.py"
click node_codex "https://github.com/bua9595/pets/blob/main/src/codex_pet_builder.py"
click node_codexassets "https://github.com/bua9595/pets/tree/main/assets/codex/ruffy"
click node_skillpackage "https://github.com/bua9595/pets/tree/main/assets/hatch-skill/hatch-real-pet"

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_desktop,node_animator,node_petdata toneBlue
class node_cli,node_hatchflow,node_pet,node_state,node_actions,node_lookloader toneAmber
class node_approved,node_review,node_ruffybuilder,node_chibibuilder,node_qa toneMint
class node_skillloader,node_skills,node_codex,node_codexassets,node_skillpackage toneRose
class node_user toneIndigo
```

## Components

### Pet runtime

- [Desktop window](https://github.com/bua9595/pets/blob/main/src/desktop_pet.py): `src/desktop_pet.py`
- [Sprite animator](https://github.com/bua9595/pets/blob/main/src/sprite_animator.py): `src/sprite_animator.py`
- [Pet manifests and atlases](https://github.com/bua9595/pets/tree/main/assets/pets): `assets/pets`

### CLI interactions

- [Hatch CLI](https://github.com/bua9595/pets/blob/main/src/main.py): `src/main.py`
- [Hatch flow](https://github.com/bua9595/pets/blob/main/src/hatch_flow.py): `src/hatch_flow.py`
- [Pet state and actions](https://github.com/bua9595/pets/blob/main/src/pet.py): `src/pet.py`
- [Pet state model](https://github.com/bua9595/pets/blob/main/src/pet_state.py): `src/pet_state.py`
- [Action handler](https://github.com/bua9595/pets/blob/main/src/actions.py): `src/actions.py`
- [Look and asset loader](https://github.com/bua9595/pets/blob/main/src/asset_loader.py): `src/asset_loader.py`

### Sprite assets

- [Approved sprite sources](https://github.com/bua9595/pets/tree/main/assets/source_approved): `assets/source_approved`
- [Source review workflow](https://github.com/bua9595/pets/tree/main/assets/review): `assets/review`
- [Ruffy atlas builder](https://github.com/bua9595/pets/blob/main/src/pet1_ruffy_builder.py): `src/pet1_ruffy_builder.py`
- [Chibi atlas builder](https://github.com/bua9595/pets/blob/main/src/pet2_chibi_builder.py): `src/pet2_chibi_builder.py`
- [Sprite QA](https://github.com/bua9595/pets/blob/main/src/sprite_qa.py): `src/sprite_qa.py`

### Exports and skills

- [Skill loader](https://github.com/bua9595/pets/blob/main/src/skill_loader.py): `src/skill_loader.py`
- [Skill definitions](https://github.com/bua9595/pets/blob/main/src/skills.py): `src/skills.py`
- [Codex pet export](https://github.com/bua9595/pets/blob/main/src/codex_pet_builder.py): `src/codex_pet_builder.py`
- [Codex pet package](https://github.com/bua9595/pets/tree/main/assets/codex/ruffy): `assets/codex/ruffy`
- [Hatch pet skill](https://github.com/bua9595/pets/tree/main/assets/hatch-skill/hatch-real-pet): `assets/hatch-skill/hatch-real-pet`

### Other components

- **Pet owner**

## Connections

- Pet owner → Desktop window: starts or controls
- Desktop window → Sprite animator: plays animations
- Sprite animator → Pet manifests and atlases: reads manifest and atlas
- Pet owner → Hatch CLI: runs commands
- Hatch CLI → Look and asset loader: loads look
- Hatch CLI → Hatch flow: starts hatch flow
- Hatch CLI → Pet state and actions: creates pet
- Hatch CLI → Action handler: dispatches action
- Hatch flow → Pet state and actions: applies gear or skill
- Pet state and actions → Pet state model: updates state
- Action handler → Pet state and actions: performs action
- Skill loader → Skill definitions: loads skills
- Hatch flow → Skill loader: loads skills
- Source review workflow → Approved sprite sources: approves sources
- Approved sprite sources → Ruffy atlas builder: provides source sprites
- Approved sprite sources → Chibi atlas builder: provides source sprites
- Ruffy atlas builder → Pet manifests and atlases: writes Ruffy atlas and manifest
- Chibi atlas builder → Pet manifests and atlases: writes Chibi atlas and manifest
- Ruffy atlas builder → Sprite QA: produces QA results
- Chibi atlas builder → Sprite QA: produces QA results
- Pet manifests and atlases → Codex pet export: supplies runtime atlas
- Codex pet export → Codex pet package: writes pet package
- Hatch pet skill → Pet owner: guides asset creation