# aspire488/pipo architecture

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

- Interactive diagram: https://gitdiagram.com/aspire488/pipo
- Repository: https://github.com/aspire488/pipo

## Overview

Pipo is an Android character-life simulation, with a separate browser world and classic demo. The main Android journey is opening the room, loading persistent character state, advancing Pipo’s autonomous life, and presenting the resulting scene and interactions. The app also supports Nib, trips, projects, mysteries, games, voice, notifications, optional AI, and real weather. Relationships below follow sampled calls, SOURCE INDEX references, or README statements; browser capabilities are documented, but their full runtime details were not inspected.

Main entry points: [`app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt) (Room experience), [`app/src/main/java/com/pipo/robot/engine/Simulator.kt`](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Simulator.kt) (Life simulation), [`app/src/main/java/com/pipo/robot/MainActivity.kt`](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/MainActivity.kt) (App entry), [`web/src/main.js`](https://github.com/aspire488/pipo/blob/main/web/src/main.js) (Living 3D world)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android_ui["Android experience"]
  node_activity["App entry<br/>[MainActivity.kt]"]
  node_home["Room experience<br/>[HomeViewModel.kt]"]
  node_render["Room rendering<br/>[RoomPainter.kt]"]
  node_screens["Other screens<br/>[Screens.kt]"]
  node_map["World map<br/>[MapScreen.kt]"]
  node_nib_screen["Nib screen<br/>[NibScreen.kt]"]
end

subgraph group_life["Character simulation"]
  node_behavior["Behavior selection<br/>[BehaviorEngine.kt]"]
  node_simulator["Life simulation<br/>[Simulator.kt]"]
  node_experience["Memory and growth<br/>[Experience.kt]"]
  node_dialogue["Character dialogue<br/>[Dialogue.kt]"]
  node_trips["Trips and places<br/>[Trips.kt]"]
  node_mystery["Mysteries<br/>[Mystery.kt]"]
  node_nib["Nib behavior<br/>[PetEngine.kt]"]
  node_world["World simulation<br/>[WorldEngine.kt]"]
end

subgraph group_state["Persistence and data"]
  node_catalog["Items and projects<br/>[Catalog.kt]"]
  node_repository[("Local save<br/>[PipoRepository.kt]")]
end

subgraph group_integrations["Optional integrations"]
  node_worker["Away-time worker<br/>[PipoWorker.kt]"]
  node_notifier["Notifications<br/>[Notifier.kt]"]
  node_voice["Voice service"]
  node_voice_listener["Voice controls"]
  node_ai["AI chat<br/>[ChatBrain.kt]"]
  node_weather["Real weather<br/>[RealWeather.kt]"]
end

node_user(("Phone user"))
node_browser["Living 3D world<br/>[main.js]"]
node_browser_brain["Browser character brain<br/>[brain.js]"]
node_browser_scene["Browser scene<br/>[scene.js]"]
node_classic["Classic 2D demo<br/>[app.js]"]

node_user -->|"opens"| node_activity
node_activity -->|"shows"| node_home
node_home -->|"reads state"| node_repository
node_home -->|"requests behavior"| node_behavior
node_home -->|"requests dialogue"| node_dialogue
node_home -->|"advances life"| node_simulator
node_home -.->|"presents room"| node_render
node_activity -->|"routes screens"| node_screens
node_activity -->|"routes map"| node_map
node_activity -->|"routes Nib"| node_nib_screen
node_simulator -->|"selects activities"| node_behavior
node_simulator -->|"advances trips"| node_trips
node_simulator -->|"advances mysteries"| node_mystery
node_simulator -->|"advances Nib"| node_nib
node_simulator -->|"generates dialogue"| node_dialogue
node_simulator -->|"uses weather"| node_weather
node_behavior -->|"uses definitions"| node_catalog
node_experience -->|"describes items"| node_catalog
node_world -->|"uses definitions"| node_catalog
node_mystery -->|"involves Nib"| node_nib
node_home -->|"uses memories"| node_experience
node_home -.->|"requests AI"| node_ai
node_home -->|"persists changes"| node_repository
node_worker -->|"loads state"| node_repository
node_worker -->|"catches up life"| node_simulator
node_worker -->|"posts decision"| node_notifier
node_activity -->|"starts voice"| node_voice_listener
node_voice_listener -->|"starts service"| node_voice
node_user -->|"visits world"| node_browser
node_browser -->|"runs character"| node_browser_brain
node_browser -->|"builds scene"| node_browser_scene
node_browser -->|"opens classic demo"| node_classic

click node_activity "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/MainActivity.kt"
click node_home "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt"
click node_render "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/render/RoomPainter.kt"
click node_screens "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/screens/Screens.kt"
click node_map "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/screens/MapScreen.kt"
click node_nib_screen "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/screens/NibScreen.kt"
click node_behavior "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/BehaviorEngine.kt"
click node_simulator "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Simulator.kt"
click node_experience "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Experience.kt"
click node_dialogue "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Dialogue.kt"
click node_trips "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Trips.kt"
click node_mystery "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Mystery.kt"
click node_nib "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/PetEngine.kt"
click node_world "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/WorldEngine.kt"
click node_catalog "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/data/Catalog.kt"
click node_repository "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/data/PipoRepository.kt"
click node_worker "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/notify/PipoWorker.kt"
click node_notifier "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/notify/Notifier.kt"
click node_voice "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/voice/PipoVoiceService.kt"
click node_voice_listener "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/voice/PipoVoiceListener.kt"
click node_ai "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ai/ChatBrain.kt"
click node_weather "https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/data/RealWeather.kt"
click node_browser "https://github.com/aspire488/pipo/blob/main/web/src/main.js"
click node_browser_brain "https://github.com/aspire488/pipo/blob/main/web/src/brain.js"
click node_browser_scene "https://github.com/aspire488/pipo/blob/main/web/src/scene.js"
click node_classic "https://github.com/aspire488/pipo/blob/main/web/classic/app.js"

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_activity,node_home,node_render,node_screens,node_map,node_nib_screen,node_user,node_browser_brain,node_browser_scene toneBlue
class node_behavior,node_simulator,node_experience,node_dialogue,node_trips,node_mystery,node_nib,node_world toneAmber
class node_catalog,node_repository toneMint
class node_worker,node_notifier,node_voice,node_voice_listener,node_ai,node_weather toneRose
class node_browser,node_classic toneTeal
```

## Components

### Android experience

- [App entry](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/MainActivity.kt): `app/src/main/java/com/pipo/robot/MainActivity.kt`
- [Room experience](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt): `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`
- [Room rendering](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/render/RoomPainter.kt): `app/src/main/java/com/pipo/robot/ui/render/RoomPainter.kt`
- [Other screens](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/screens/Screens.kt): `app/src/main/java/com/pipo/robot/ui/screens/Screens.kt`
- [World map](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/screens/MapScreen.kt): `app/src/main/java/com/pipo/robot/ui/screens/MapScreen.kt`
- [Nib screen](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ui/screens/NibScreen.kt): `app/src/main/java/com/pipo/robot/ui/screens/NibScreen.kt`

### Character simulation

- [Behavior selection](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/BehaviorEngine.kt): `app/src/main/java/com/pipo/robot/engine/BehaviorEngine.kt`
- [Life simulation](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Simulator.kt): `app/src/main/java/com/pipo/robot/engine/Simulator.kt`
- [Memory and growth](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Experience.kt): `app/src/main/java/com/pipo/robot/engine/Experience.kt`
- [Character dialogue](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Dialogue.kt): `app/src/main/java/com/pipo/robot/engine/Dialogue.kt`
- [Trips and places](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Trips.kt): `app/src/main/java/com/pipo/robot/engine/Trips.kt`
- [Mysteries](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/Mystery.kt): `app/src/main/java/com/pipo/robot/engine/Mystery.kt`
- [Nib behavior](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/PetEngine.kt): `app/src/main/java/com/pipo/robot/engine/PetEngine.kt`
- [World simulation](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/engine/WorldEngine.kt): `app/src/main/java/com/pipo/robot/engine/WorldEngine.kt`

### Persistence and data

- [Items and projects](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/data/Catalog.kt): `app/src/main/java/com/pipo/robot/data/Catalog.kt`
- [Local save](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/data/PipoRepository.kt): `app/src/main/java/com/pipo/robot/data/PipoRepository.kt`

### Optional integrations

- [Away-time worker](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/notify/PipoWorker.kt): `app/src/main/java/com/pipo/robot/notify/PipoWorker.kt`
- [Notifications](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/notify/Notifier.kt): `app/src/main/java/com/pipo/robot/notify/Notifier.kt`
- [Voice service](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/voice/PipoVoiceService.kt): `app/src/main/java/com/pipo/robot/voice/PipoVoiceService.kt`
- [Voice controls](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/voice/PipoVoiceListener.kt): `app/src/main/java/com/pipo/robot/voice/PipoVoiceListener.kt`
- [AI chat](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/ai/ChatBrain.kt): `app/src/main/java/com/pipo/robot/ai/ChatBrain.kt`
- [Real weather](https://github.com/aspire488/pipo/blob/main/app/src/main/java/com/pipo/robot/data/RealWeather.kt): `app/src/main/java/com/pipo/robot/data/RealWeather.kt`

### Other components

- **Phone user**
- [Living 3D world](https://github.com/aspire488/pipo/blob/main/web/src/main.js): `web/src/main.js`
- [Browser character brain](https://github.com/aspire488/pipo/blob/main/web/src/brain.js): `web/src/brain.js`
- [Browser scene](https://github.com/aspire488/pipo/blob/main/web/src/scene.js): `web/src/scene.js`
- [Classic 2D demo](https://github.com/aspire488/pipo/blob/main/web/classic/app.js): `web/classic/app.js`

## Connections

- Phone user → App entry: opens (evidence: `README.md`)
- App entry → Room experience: shows (evidence: `app/src/main/java/com/pipo/robot/MainActivity.kt`)
- Room experience → Local save: reads state (evidence: `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`)
- Room experience → Behavior selection: requests behavior (evidence: `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`)
- Room experience → Character dialogue: requests dialogue (evidence: `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`)
- Room experience → Life simulation: advances life (evidence: `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`)
- Room experience → Room rendering: presents room
- App entry → Other screens: routes screens (evidence: `app/src/main/java/com/pipo/robot/MainActivity.kt`)
- App entry → World map: routes map (evidence: `app/src/main/java/com/pipo/robot/MainActivity.kt`)
- App entry → Nib screen: routes Nib (evidence: `app/src/main/java/com/pipo/robot/MainActivity.kt`)
- Life simulation → Behavior selection: selects activities (evidence: `app/src/main/java/com/pipo/robot/engine/Simulator.kt`)
- Life simulation → Trips and places: advances trips (evidence: `app/src/main/java/com/pipo/robot/engine/Simulator.kt`)
- Life simulation → Mysteries: advances mysteries (evidence: `app/src/main/java/com/pipo/robot/engine/Simulator.kt`)
- Life simulation → Nib behavior: advances Nib (evidence: `app/src/main/java/com/pipo/robot/engine/Simulator.kt`)
- Life simulation → Character dialogue: generates dialogue (evidence: `app/src/main/java/com/pipo/robot/engine/Simulator.kt`)
- Life simulation → Real weather: uses weather (evidence: `app/src/main/java/com/pipo/robot/engine/Simulator.kt`)
- Behavior selection → Items and projects: uses definitions (evidence: `app/src/main/java/com/pipo/robot/engine/BehaviorEngine.kt`)
- Memory and growth → Items and projects: describes items (evidence: `app/src/main/java/com/pipo/robot/engine/Experience.kt`)
- World simulation → Items and projects: uses definitions (evidence: `app/src/main/java/com/pipo/robot/engine/WorldEngine.kt`)
- Mysteries → Nib behavior: involves Nib (evidence: `app/src/main/java/com/pipo/robot/engine/Mystery.kt`)
- Room experience → Memory and growth: uses memories (evidence: `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`)
- Room experience → AI chat: requests AI (evidence: `README.md`)
- Room experience → Local save: persists changes (evidence: `app/src/main/java/com/pipo/robot/ui/home/HomeViewModel.kt`)
- Away-time worker → Local save: loads state (evidence: `app/src/main/java/com/pipo/robot/notify/PipoWorker.kt`)
- Away-time worker → Life simulation: catches up life (evidence: `app/src/main/java/com/pipo/robot/notify/PipoWorker.kt`)
- Away-time worker → Notifications: posts decision (evidence: `app/src/main/java/com/pipo/robot/notify/PipoWorker.kt`)
- App entry → Voice controls: starts voice (evidence: `app/src/main/java/com/pipo/robot/MainActivity.kt`)
- Voice controls → Voice service: starts service (evidence: `app/src/main/java/com/pipo/robot/voice/PipoVoiceListener.kt`)
- Phone user → Living 3D world: visits world (evidence: `README.md`)
- Living 3D world → Browser character brain: runs character (evidence: `web/src/main.js`)
- Living 3D world → Browser scene: builds scene (evidence: `web/src/main.js`)
- Living 3D world → Classic 2D demo: opens classic demo (evidence: `README.md`)
