# theapogeus/pestinha architecture

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

- Interactive diagram: https://gitdiagram.com/theapogeus/pestinha
- Repository: https://github.com/theapogeus/pestinha

## Overview

Pestinha is a cross-platform desktop screen pet. The main workflow starts with launch and settings, then the app samples computer activity and user gestures, updates neural and behavioral state, and presents the pet and its reactions as desktop overlays. Its documented behavior also includes play, work/notebook, mischief, protest, sadness, punishment, sleep, and fireworks. The app composition is excerpted, but many controller and feature implementations are not; only evidenced connections are drawn, and key unsampled capabilities are retained without speculative call arrows.

Main entry points: [`pestinha/app.py`](https://github.com/theapogeus/pestinha/blob/main/pestinha/app.py) (App coordinator), [`pestinha/body/pet.py`](https://github.com/theapogeus/pestinha/blob/main/pestinha/body/pet.py) (Pet body), [`main.py`](https://github.com/theapogeus/pestinha/blob/main/main.py) (Launch), [`pestinha/mind/protest_ctl.py`](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/protest_ctl.py) (Protest controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and settings"]
  node_entry["Launch<br/>[main.py]"]
  node_settings["Settings UI<br/>[ui.py]"]
  node_onboarding["Onboarding<br/>[onboarding.py]"]
  node_app["App coordinator<br/>[app.py]"]
end

subgraph group_sensing["Sensing and decision"]
  node_sensors["System senses<br/>[senses.py]"]
  node_timeline["Activity timeline<br/>[timeline.py]"]
  node_neural["Neural network<br/>[nervous_system.py]"]
  node_emotion["Emotion state<br/>[emotion.py]"]
  node_conditioning["Learning<br/>[conditioning.py]"]
  node_episodic["Episode memory<br/>[episodic.py]"]
end

subgraph group_pet["Pet and behavior"]
  node_body["Pet body<br/>[pet.py]"]
  node_behavior["Body behavior<br/>[behavior.py]"]
  node_physics["Physics<br/>[physics.py]"]
  node_interaction["User gestures<br/>[interacao.py]"]
  node_play["Ball play<br/>[brincadeira.py]"]
  node_work["Work companion<br/>[mesa.py]"]
  node_mischief["Mischief<br/>[mischief_ctl.py]"]
  node_protest["Protest stages<br/>[protesto.py]"]
  node_protestctl["Protest controller<br/>[protest_ctl.py]"]
  node_punishment["Punishment corner<br/>[castigo_ctl.py]"]
  node_sadness["Sadness<br/>[protest_ctl.py]"]
  node_sleep["Sleep behavior<br/>[sleep.py]"]
end

subgraph group_world["World and presentation"]
  node_fireworks["Fireworks<br/>[fireworks.py]"]
  node_worlditems["Floating items<br/>[objetos.py]"]
  node_posters["Posters<br/>[cartazes.py]"]
  node_notebook["Notebook overlay<br/>[notebook.py]"]
  node_mischiefview["Mischief overlay<br/>[mischief.py]"]
  node_ui["Tray and panels<br/>[ui.py]"]
  node_platform["Platform adapters<br/>[__init__.py]"]
end

subgraph group_state["Persistence"]
  node_paths["Data paths<br/>[paths.py]"]
  node_store[("State store<br/>[store.py]")]
  node_settingsstore["Settings persistence<br/>[settings_store.py]"]
end

node_user(("Computer user"))
node_desktop["Desktop environment"]

node_user -->|"launches"| node_entry
node_entry -->|"opens settings"| node_settings
node_entry -->|"shows first-run"| node_onboarding
node_entry -->|"creates"| node_app
node_settings -->|"updates preferences"| node_settingsstore
node_settingsstore -->|"persists via"| node_store
node_app -->|"resolves data"| node_paths
node_app -->|"samples"| node_sensors
node_sensors -->|"queries system"| node_platform
node_app -->|"coordinates"| node_timeline
node_app -->|"coordinates"| node_neural
node_app -->|"coordinates"| node_emotion
node_app -->|"creates"| node_body
node_app -->|"creates"| node_behavior
node_app -->|"mixes in"| node_interaction
node_app -->|"creates"| node_mischief
node_app -->|"creates"| node_work
node_behavior -->|"uses"| node_physics
node_body -->|"uses"| node_physics
node_user -->|"gestures on"| node_body
node_interaction -->|"handles gestures"| node_body
node_app -->|"coordinates"| node_protest
node_app -->|"creates"| node_protestctl
node_protestctl -->|"updates stages"| node_protest
node_protestctl -->|"creates signs"| node_posters
node_punishment -->|"creates signs"| node_posters
node_protest -.->|"loads state"| node_store
node_app -.->|"coordinates learning"| node_conditioning
node_app -.->|"coordinates memory"| node_episodic
node_mischief -->|"presents mischief"| node_mischiefview
node_work -->|"uses overlay"| node_notebook
node_protestctl -->|"uses items"| node_worlditems
node_user -->|"uses"| node_desktop
node_desktop -->|"provides activity data"| node_sensors
node_body -.->|"displays pet"| node_desktop
node_app -.->|"coordinates behavior"| node_sleep
node_app -.->|"coordinates effect"| node_fireworks
node_app -.->|"coordinates behavior"| node_sadness
node_app -.->|"coordinates behavior"| node_punishment
node_app -.->|"coordinates play"| node_play
node_app -.->|"coordinates interface"| node_ui

click node_entry "https://github.com/theapogeus/pestinha/blob/main/main.py"
click node_settings "https://github.com/theapogeus/pestinha/blob/main/pestinha/ui/ui.py"
click node_onboarding "https://github.com/theapogeus/pestinha/blob/main/pestinha/ui/onboarding.py"
click node_app "https://github.com/theapogeus/pestinha/blob/main/pestinha/app.py"
click node_sensors "https://github.com/theapogeus/pestinha/blob/main/pestinha/sense/senses.py"
click node_timeline "https://github.com/theapogeus/pestinha/blob/main/pestinha/sense/timeline.py"
click node_neural "https://github.com/theapogeus/pestinha/blob/main/pestinha/core/nervous_system.py"
click node_emotion "https://github.com/theapogeus/pestinha/blob/main/pestinha/core/emotion.py"
click node_conditioning "https://github.com/theapogeus/pestinha/blob/main/pestinha/core/conditioning.py"
click node_episodic "https://github.com/theapogeus/pestinha/blob/main/pestinha/core/episodic.py"
click node_body "https://github.com/theapogeus/pestinha/blob/main/pestinha/body/pet.py"
click node_behavior "https://github.com/theapogeus/pestinha/blob/main/pestinha/body/behavior.py"
click node_physics "https://github.com/theapogeus/pestinha/blob/main/pestinha/core/physics.py"
click node_interaction "https://github.com/theapogeus/pestinha/blob/main/pestinha/controle/interacao.py"
click node_play "https://github.com/theapogeus/pestinha/blob/main/pestinha/body/brincadeira.py"
click node_work "https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/mesa.py"
click node_mischief "https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/mischief_ctl.py"
click node_protest "https://github.com/theapogeus/pestinha/blob/main/pestinha/core/protesto.py"
click node_protestctl "https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/protest_ctl.py"
click node_punishment "https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/castigo_ctl.py"
click node_sadness "https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/protest_ctl.py"
click node_sleep "https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/sleep.py"
click node_fireworks "https://github.com/theapogeus/pestinha/blob/main/pestinha/world/fireworks.py"
click node_worlditems "https://github.com/theapogeus/pestinha/blob/main/pestinha/world/objetos.py"
click node_posters "https://github.com/theapogeus/pestinha/blob/main/pestinha/world/cartazes.py"
click node_notebook "https://github.com/theapogeus/pestinha/blob/main/pestinha/world/notebook.py"
click node_mischiefview "https://github.com/theapogeus/pestinha/blob/main/pestinha/world/mischief.py"
click node_ui "https://github.com/theapogeus/pestinha/blob/main/pestinha/ui/ui.py"
click node_platform "https://github.com/theapogeus/pestinha/blob/main/pestinha/plataforma/__init__.py"
click node_paths "https://github.com/theapogeus/pestinha/blob/main/pestinha/paths.py"
click node_store "https://github.com/theapogeus/pestinha/blob/main/pestinha/store.py"
click node_settingsstore "https://github.com/theapogeus/pestinha/blob/main/pestinha/settings_store.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_entry,node_settings,node_onboarding,node_app,node_user toneBlue
class node_sensors,node_timeline,node_neural,node_emotion,node_conditioning,node_episodic toneAmber
class node_body,node_behavior,node_physics,node_interaction,node_play,node_work,node_mischief,node_protest,node_protestctl,node_punishment,node_sadness,node_sleep toneMint
class node_fireworks,node_worlditems,node_posters,node_notebook,node_mischiefview,node_ui,node_platform toneRose
class node_paths,node_store,node_settingsstore,node_desktop toneIndigo
```

## Components

### Startup and settings

- [Launch](https://github.com/theapogeus/pestinha/blob/main/main.py): `main.py`
- [Settings UI](https://github.com/theapogeus/pestinha/blob/main/pestinha/ui/ui.py): `pestinha/ui/ui.py`
- [Onboarding](https://github.com/theapogeus/pestinha/blob/main/pestinha/ui/onboarding.py): `pestinha/ui/onboarding.py`
- [App coordinator](https://github.com/theapogeus/pestinha/blob/main/pestinha/app.py): `pestinha/app.py`

### Sensing and decision

- [System senses](https://github.com/theapogeus/pestinha/blob/main/pestinha/sense/senses.py): `pestinha/sense/senses.py`
- [Activity timeline](https://github.com/theapogeus/pestinha/blob/main/pestinha/sense/timeline.py): `pestinha/sense/timeline.py`
- [Neural network](https://github.com/theapogeus/pestinha/blob/main/pestinha/core/nervous_system.py): `pestinha/core/nervous_system.py`
- [Emotion state](https://github.com/theapogeus/pestinha/blob/main/pestinha/core/emotion.py): `pestinha/core/emotion.py`
- [Learning](https://github.com/theapogeus/pestinha/blob/main/pestinha/core/conditioning.py): `pestinha/core/conditioning.py`
- [Episode memory](https://github.com/theapogeus/pestinha/blob/main/pestinha/core/episodic.py): `pestinha/core/episodic.py`

### Pet and behavior

- [Pet body](https://github.com/theapogeus/pestinha/blob/main/pestinha/body/pet.py): `pestinha/body/pet.py`
- [Body behavior](https://github.com/theapogeus/pestinha/blob/main/pestinha/body/behavior.py): `pestinha/body/behavior.py`
- [Physics](https://github.com/theapogeus/pestinha/blob/main/pestinha/core/physics.py): `pestinha/core/physics.py`
- [User gestures](https://github.com/theapogeus/pestinha/blob/main/pestinha/controle/interacao.py): `pestinha/controle/interacao.py`
- [Ball play](https://github.com/theapogeus/pestinha/blob/main/pestinha/body/brincadeira.py): `pestinha/body/brincadeira.py`
- [Work companion](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/mesa.py): `pestinha/mind/mesa.py`
- [Mischief](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/mischief_ctl.py): `pestinha/mind/mischief_ctl.py`
- [Protest stages](https://github.com/theapogeus/pestinha/blob/main/pestinha/core/protesto.py): `pestinha/core/protesto.py`
- [Protest controller](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/protest_ctl.py): `pestinha/mind/protest_ctl.py`
- [Punishment corner](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/castigo_ctl.py): `pestinha/mind/castigo_ctl.py`
- [Sadness](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/protest_ctl.py): `pestinha/mind/protest_ctl.py`
- [Sleep behavior](https://github.com/theapogeus/pestinha/blob/main/pestinha/mind/sleep.py): `pestinha/mind/sleep.py`

### World and presentation

- [Fireworks](https://github.com/theapogeus/pestinha/blob/main/pestinha/world/fireworks.py): `pestinha/world/fireworks.py`
- [Floating items](https://github.com/theapogeus/pestinha/blob/main/pestinha/world/objetos.py): `pestinha/world/objetos.py`
- [Posters](https://github.com/theapogeus/pestinha/blob/main/pestinha/world/cartazes.py): `pestinha/world/cartazes.py`
- [Notebook overlay](https://github.com/theapogeus/pestinha/blob/main/pestinha/world/notebook.py): `pestinha/world/notebook.py`
- [Mischief overlay](https://github.com/theapogeus/pestinha/blob/main/pestinha/world/mischief.py): `pestinha/world/mischief.py`
- [Tray and panels](https://github.com/theapogeus/pestinha/blob/main/pestinha/ui/ui.py): `pestinha/ui/ui.py`
- [Platform adapters](https://github.com/theapogeus/pestinha/blob/main/pestinha/plataforma/__init__.py): `pestinha/plataforma/__init__.py`

### Persistence

- [Data paths](https://github.com/theapogeus/pestinha/blob/main/pestinha/paths.py): `pestinha/paths.py`
- [State store](https://github.com/theapogeus/pestinha/blob/main/pestinha/store.py): `pestinha/store.py`
- [Settings persistence](https://github.com/theapogeus/pestinha/blob/main/pestinha/settings_store.py): `pestinha/settings_store.py`

### Other components

- **Computer user**
- **Desktop environment**

## Connections

- Computer user → Launch: launches (evidence: `main.py`)
- Launch → Settings UI: opens settings (evidence: `main.py`)
- Launch → Onboarding: shows first-run (evidence: `main.py`)
- Launch → App coordinator: creates (evidence: `pestinha/app.py`)
- Settings UI → Settings persistence: updates preferences (evidence: `main.py`)
- Settings persistence → State store: persists via (evidence: `pestinha/settings_store.py`)
- App coordinator → Data paths: resolves data (evidence: `pestinha/app.py`)
- App coordinator → System senses: samples (evidence: `pestinha/app.py`)
- System senses → Platform adapters: queries system (evidence: `pestinha/sense/senses.py`)
- App coordinator → Activity timeline: coordinates (evidence: `pestinha/app.py`)
- App coordinator → Neural network: coordinates (evidence: `pestinha/app.py`)
- App coordinator → Emotion state: coordinates (evidence: `pestinha/app.py`)
- App coordinator → Pet body: creates (evidence: `pestinha/app.py`)
- App coordinator → Body behavior: creates (evidence: `pestinha/app.py`)
- App coordinator → User gestures: mixes in (evidence: `pestinha/app.py`)
- App coordinator → Mischief: creates (evidence: `pestinha/app.py`)
- App coordinator → Work companion: creates (evidence: `pestinha/app.py`)
- Body behavior → Physics: uses (evidence: `pestinha/body/behavior.py`)
- Pet body → Physics: uses (evidence: `pestinha/body/pet.py`)
- Computer user → Pet body: gestures on (evidence: `pestinha/body/pet.py`)
- User gestures → Pet body: handles gestures (evidence: `pestinha/controle/interacao.py`)
- App coordinator → Protest stages: coordinates (evidence: `pestinha/app.py`)
- App coordinator → Protest controller: creates (evidence: `pestinha/app.py`)
- Protest controller → Protest stages: updates stages (evidence: `pestinha/mind/protest_ctl.py`)
- Protest controller → Posters: creates signs (evidence: `pestinha/mind/protest_ctl.py`)
- Punishment corner → Posters: creates signs (evidence: `pestinha/mind/castigo_ctl.py`)
- Protest stages → State store: loads state (evidence: `pestinha/core/protesto.py`)
- App coordinator → Learning: coordinates learning (evidence: `pestinha/app.py`)
- App coordinator → Episode memory: coordinates memory (evidence: `pestinha/app.py`)
- Mischief → Mischief overlay: presents mischief (evidence: `pestinha/world/mischief.py`)
- Work companion → Notebook overlay: uses overlay (evidence: `pestinha/mind/mesa.py`)
- Protest controller → Floating items: uses items (evidence: `pestinha/mind/protest_ctl.py`)
- Computer user → Desktop environment: uses
- Desktop environment → System senses: provides activity data
- Pet body → Desktop environment: displays pet
- App coordinator → Sleep behavior: coordinates behavior (evidence: `pestinha/app.py`)
- App coordinator → Fireworks: coordinates effect
- App coordinator → Sadness: coordinates behavior (evidence: `pestinha/app.py`)
- App coordinator → Punishment corner: coordinates behavior (evidence: `pestinha/app.py`)
- App coordinator → Ball play: coordinates play (evidence: `pestinha/app.py`)
- App coordinator → Tray and panels: coordinates interface (evidence: `pestinha/app.py`)
