# cooklaye/studypet_portable architecture

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

- Interactive diagram: https://gitdiagram.com/cooklaye/studypet_portable
- Repository: https://github.com/cooklaye/studypet_portable

## Overview

StudyPet is a Tkinter emotional-support companion: students launch into a pet-centered study space, build a bond through study and care, and can use stress check-ins and relaxation tools. The app also includes local AI chat, music, task planning, drowsiness monitoring, and recovery of saved progress. The graph follows documented imports and README-described behavior; some subsystem internals are represented by their exact directories because their implementation files were not excerpted.

Main entry points: [`src/screens/main_game_screen.py`](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/main_game_screen.py) (Main game), [`src/StudyPet.py`](https://github.com/cooklaye/studypet_portable/blob/main/src/StudyPet.py) (App entry), [`src/models/app_state.py`](https://github.com/cooklaye/studypet_portable/blob/main/src/models/app_state.py) (App state), [`src/utils/stress_diagnosis.py`](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/stress_diagnosis.py) (Stress scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and screens"]
  node_entry["App entry<br/>[StudyPet.py]"]
  node_onboarding["Onboarding<br/>[greeting_screen.py]"]
  node_pet_select["Pet selection"]
  node_hatch["Hatching<br/>[hatch_screen.py]"]
  node_game["Main game"]
end

subgraph group_pet["Pet and persistence"]
  node_pet_model["Pet evolution<br/>[pet.py]"]
  node_app_state["App state<br/>[app_state.py]"]
  node_user["User profile<br/>[user.py]"]
  node_state_manager["Pet state events<br/>[state_manager.py]"]
  node_session["Session recovery<br/>[session_manager.py]"]
  node_file_utils["File utilities<br/>[file_utils.py]"]
end

subgraph group_wellbeing["Well-being"]
  node_stress_gate["Stress access gate"]
  node_stress_panels["Stress check-in panels<br/>[stress_panels.py]"]
  node_scanner["Facial stress scan<br/>[live_scan.py]"]
  node_diagnosis["Stress scoring"]
  node_keywords["Rant analysis<br/>[stress_keywords.py]"]
  node_mailbox["Stress mailbox<br/>[stress_mailbox.py]"]
  node_diagnosis_flow["Diagnosis flow<br/>[diagnosis_flow.py]"]
  node_breathing["Breathing exercise"]
  node_drowsiness["Drowsiness monitor"]
end

subgraph group_study["Study tools"]
  node_chat["AI companion chat<br/>[chatbot_utils.py]"]
  node_model_manager["Local AI manager<br/>[model_manager.py]"]
  node_ai_server["Local AI server"]
  node_tasks["Task planner<br/>[tasks_panel.py]"]
  node_scheduler["Study scheduler"]
  node_music["Music player<br/>[music_player.py]"]
  node_music_analysis["Music analysis<br/>[music_analysis.py]"]
end

subgraph group_ui["Interface components"]
  node_graphics["Pet renderer<br/>[pet_graphics.py]"]
  node_playground["Playground renderer"]
  node_settings["Settings window"]
  node_theme["Theme<br/>[simple_theme.py]"]
  node_pet_theme["Pet theme<br/>[pet_theme.py]"]
  node_widgets["Rounded widgets<br/>[rounded_widgets.py]"]
end

node_student(("Student"))

node_student -->|"launches"| node_entry
node_entry -->|"opens"| node_onboarding
node_entry -->|"opens"| node_pet_select
node_entry -->|"opens"| node_hatch
node_entry -->|"opens"| node_game
node_entry -->|"loads"| node_app_state
node_entry -->|"uses"| node_session
node_entry -->|"opens"| node_stress_gate
node_pet_select -->|"selects"| node_pet_model
node_pet_select -->|"renders"| node_graphics
node_hatch -->|"renders"| node_graphics
node_game -->|"reads"| node_pet_model
node_game -->|"renders"| node_playground
node_game -->|"renders"| node_graphics
node_pet_model -->|"notifies"| node_state_manager
node_app_state -->|"manages"| node_pet_model
node_app_state -->|"manages"| node_user
node_app_state -->|"uses"| node_file_utils
node_app_state -.->|"saves progress"| node_session
node_game -->|"sends messages"| node_chat
node_game -->|"manages AI"| node_model_manager
node_model_manager -->|"communicates"| node_ai_server
node_game -->|"opens"| node_mailbox
node_game -->|"opens"| node_diagnosis_flow
node_game -->|"opens"| node_breathing
node_stress_gate -->|"shows"| node_stress_panels
node_stress_gate -->|"uses"| node_diagnosis
node_stress_panels -->|"starts scan"| node_scanner
node_stress_panels -->|"scores quiz"| node_diagnosis
node_diagnosis_flow -->|"uses"| node_diagnosis
node_diagnosis_flow -->|"shows"| node_stress_panels
node_diagnosis_flow -->|"offers"| node_breathing
node_mailbox -->|"submits text"| node_diagnosis
node_diagnosis -->|"analyzes rant"| node_keywords
node_game -.->|"monitors"| node_drowsiness
node_game -->|"shows tasks"| node_tasks
node_tasks -->|"saves tasks"| node_app_state
node_game -.->|"opens"| node_scheduler
node_game -->|"controls"| node_music
node_music -->|"uses"| node_music_analysis
node_game -->|"opens"| node_settings
node_game -->|"uses"| node_theme
node_game -->|"uses"| node_pet_theme
node_game -->|"uses"| node_widgets
node_settings -->|"uses"| node_theme
node_tasks -->|"uses"| node_widgets

click node_entry "https://github.com/cooklaye/studypet_portable/blob/main/src/StudyPet.py"
click node_onboarding "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/greeting_screen.py"
click node_pet_select "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/pet_selection_screen.py"
click node_hatch "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/hatch_screen.py"
click node_game "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/main_game_screen.py"
click node_pet_model "https://github.com/cooklaye/studypet_portable/blob/main/src/models/pet.py"
click node_app_state "https://github.com/cooklaye/studypet_portable/blob/main/src/models/app_state.py"
click node_user "https://github.com/cooklaye/studypet_portable/blob/main/src/models/user.py"
click node_state_manager "https://github.com/cooklaye/studypet_portable/blob/main/src/models/state_manager.py"
click node_session "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/session_manager.py"
click node_file_utils "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/file_utils.py"
click node_stress_gate "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/stress_gate_screen.py"
click node_stress_panels "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/stress_panels.py"
click node_scanner "https://github.com/cooklaye/studypet_portable/blob/main/stress_scan/live_scan.py"
click node_diagnosis "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/stress_diagnosis.py"
click node_keywords "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/stress_keywords.py"
click node_mailbox "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/stress_mailbox.py"
click node_diagnosis_flow "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/diagnosis_flow.py"
click node_breathing "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/breathing_exercise.py"
click node_drowsiness "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/drowsiness_detector.py"
click node_chat "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/chatbot_utils.py"
click node_model_manager "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/model_manager.py"
click node_tasks "https://github.com/cooklaye/studypet_portable/blob/main/src/ui/tasks_panel.py"
click node_scheduler "https://github.com/cooklaye/studypet_portable/blob/main/src/screens/scheduler_screen.py"
click node_music "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/music_player.py"
click node_music_analysis "https://github.com/cooklaye/studypet_portable/blob/main/src/utils/music_analysis.py"
click node_graphics "https://github.com/cooklaye/studypet_portable/blob/main/src/graphics/pet_graphics.py"
click node_playground "https://github.com/cooklaye/studypet_portable/blob/main/src/graphics/simple_playground.py"
click node_settings "https://github.com/cooklaye/studypet_portable/blob/main/src/ui/unified_settings.py"
click node_theme "https://github.com/cooklaye/studypet_portable/blob/main/src/ui/simple_theme.py"
click node_pet_theme "https://github.com/cooklaye/studypet_portable/blob/main/src/ui/pet_theme.py"
click node_widgets "https://github.com/cooklaye/studypet_portable/blob/main/src/ui/rounded_widgets.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_onboarding,node_pet_select,node_hatch,node_game toneBlue
class node_pet_model,node_app_state,node_user,node_state_manager,node_session,node_file_utils toneAmber
class node_stress_gate,node_stress_panels,node_scanner,node_diagnosis,node_keywords,node_mailbox,node_diagnosis_flow,node_breathing,node_drowsiness toneMint
class node_chat,node_model_manager,node_ai_server,node_tasks,node_scheduler,node_music,node_music_analysis toneRose
class node_graphics,node_playground,node_settings,node_theme,node_pet_theme,node_widgets,node_student toneIndigo
```

## Components

### App and screens

- [App entry](https://github.com/cooklaye/studypet_portable/blob/main/src/StudyPet.py): `src/StudyPet.py`
- [Onboarding](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/greeting_screen.py): `src/screens/greeting_screen.py`
- [Pet selection](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/pet_selection_screen.py): `src/screens/pet_selection_screen.py`
- [Hatching](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/hatch_screen.py): `src/screens/hatch_screen.py`
- [Main game](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/main_game_screen.py): `src/screens/main_game_screen.py`

### Pet and persistence

- [Pet evolution](https://github.com/cooklaye/studypet_portable/blob/main/src/models/pet.py): `src/models/pet.py`
- [App state](https://github.com/cooklaye/studypet_portable/blob/main/src/models/app_state.py): `src/models/app_state.py`
- [User profile](https://github.com/cooklaye/studypet_portable/blob/main/src/models/user.py): `src/models/user.py`
- [Pet state events](https://github.com/cooklaye/studypet_portable/blob/main/src/models/state_manager.py): `src/models/state_manager.py`
- [Session recovery](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/session_manager.py): `src/utils/session_manager.py`
- [File utilities](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/file_utils.py): `src/utils/file_utils.py`

### Well-being

- [Stress access gate](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/stress_gate_screen.py): `src/screens/stress_gate_screen.py`
- [Stress check-in panels](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/stress_panels.py): `src/screens/stress_panels.py`
- [Facial stress scan](https://github.com/cooklaye/studypet_portable/blob/main/stress_scan/live_scan.py): `stress_scan/live_scan.py`
- [Stress scoring](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/stress_diagnosis.py): `src/utils/stress_diagnosis.py`
- [Rant analysis](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/stress_keywords.py): `src/utils/stress_keywords.py`
- [Stress mailbox](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/stress_mailbox.py): `src/screens/stress_mailbox.py`
- [Diagnosis flow](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/diagnosis_flow.py): `src/screens/diagnosis_flow.py`
- [Breathing exercise](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/breathing_exercise.py): `src/screens/breathing_exercise.py`
- [Drowsiness monitor](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/drowsiness_detector.py): `src/utils/drowsiness_detector.py`

### Study tools

- [AI companion chat](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/chatbot_utils.py): `src/utils/chatbot_utils.py`
- [Local AI manager](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/model_manager.py): `src/utils/model_manager.py`
- **Local AI server**
- [Task planner](https://github.com/cooklaye/studypet_portable/blob/main/src/ui/tasks_panel.py): `src/ui/tasks_panel.py`
- [Study scheduler](https://github.com/cooklaye/studypet_portable/blob/main/src/screens/scheduler_screen.py): `src/screens/scheduler_screen.py`
- [Music player](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/music_player.py): `src/utils/music_player.py`
- [Music analysis](https://github.com/cooklaye/studypet_portable/blob/main/src/utils/music_analysis.py): `src/utils/music_analysis.py`

### Interface components

- [Pet renderer](https://github.com/cooklaye/studypet_portable/blob/main/src/graphics/pet_graphics.py): `src/graphics/pet_graphics.py`
- [Playground renderer](https://github.com/cooklaye/studypet_portable/blob/main/src/graphics/simple_playground.py): `src/graphics/simple_playground.py`
- [Settings window](https://github.com/cooklaye/studypet_portable/blob/main/src/ui/unified_settings.py): `src/ui/unified_settings.py`
- [Theme](https://github.com/cooklaye/studypet_portable/blob/main/src/ui/simple_theme.py): `src/ui/simple_theme.py`
- [Pet theme](https://github.com/cooklaye/studypet_portable/blob/main/src/ui/pet_theme.py): `src/ui/pet_theme.py`
- [Rounded widgets](https://github.com/cooklaye/studypet_portable/blob/main/src/ui/rounded_widgets.py): `src/ui/rounded_widgets.py`

### Other components

- **Student**

## Connections

- Student → App entry: launches (evidence: `README.md`)
- App entry → Onboarding: opens (evidence: `src/StudyPet.py`)
- App entry → Pet selection: opens (evidence: `src/StudyPet.py`)
- App entry → Hatching: opens (evidence: `src/StudyPet.py`)
- App entry → Main game: opens (evidence: `src/StudyPet.py`)
- App entry → App state: loads (evidence: `src/StudyPet.py`)
- App entry → Session recovery: uses (evidence: `src/StudyPet.py`)
- App entry → Stress access gate: opens (evidence: `src/StudyPet.py`)
- Pet selection → Pet evolution: selects (evidence: `src/screens/pet_selection_screen.py`)
- Pet selection → Pet renderer: renders (evidence: `src/screens/pet_selection_screen.py`)
- Hatching → Pet renderer: renders (evidence: `src/screens/hatch_screen.py`)
- Main game → Pet evolution: reads (evidence: `src/screens/main_game_screen.py`)
- Main game → Playground renderer: renders (evidence: `src/screens/main_game_screen.py`)
- Main game → Pet renderer: renders (evidence: `src/screens/main_game_screen.py`)
- Pet evolution → Pet state events: notifies (evidence: `src/models/app_state.py`)
- App state → Pet evolution: manages (evidence: `src/models/app_state.py`)
- App state → User profile: manages (evidence: `src/models/app_state.py`)
- App state → File utilities: uses (evidence: `src/models/app_state.py`)
- App state → Session recovery: saves progress (evidence: `README.md`)
- Main game → AI companion chat: sends messages (evidence: `src/screens/main_game_screen.py`)
- Main game → Local AI manager: manages AI (evidence: `src/screens/main_game_screen.py`)
- Local AI manager → Local AI server: communicates (evidence: `README.md`)
- Main game → Stress mailbox: opens (evidence: `src/screens/main_game_screen.py`)
- Main game → Diagnosis flow: opens (evidence: `src/screens/main_game_screen.py`)
- Main game → Breathing exercise: opens (evidence: `src/screens/main_game_screen.py`)
- Stress access gate → Stress check-in panels: shows (evidence: `src/screens/stress_gate_screen.py`)
- Stress access gate → Stress scoring: uses (evidence: `src/screens/stress_gate_screen.py`)
- Stress check-in panels → Facial stress scan: starts scan (evidence: `src/screens/stress_panels.py`)
- Stress check-in panels → Stress scoring: scores quiz (evidence: `src/screens/stress_panels.py`)
- Diagnosis flow → Stress scoring: uses (evidence: `src/screens/diagnosis_flow.py`)
- Diagnosis flow → Stress check-in panels: shows (evidence: `src/screens/diagnosis_flow.py`)
- Diagnosis flow → Breathing exercise: offers (evidence: `src/screens/diagnosis_flow.py`)
- Stress mailbox → Stress scoring: submits text (evidence: `src/screens/stress_mailbox.py`)
- Stress scoring → Rant analysis: analyzes rant (evidence: `src/utils/stress_diagnosis.py`)
- Main game → Drowsiness monitor: monitors (evidence: `README.md`)
- Main game → Task planner: shows tasks (evidence: `src/screens/main_game_screen.py`)
- Task planner → App state: saves tasks (evidence: `src/ui/tasks_panel.py`)
- Main game → Study scheduler: opens (evidence: `README.md`)
- Main game → Music player: controls (evidence: `src/StudyPet.py`)
- Music player → Music analysis: uses (evidence: `src/utils/music_player.py`)
- Main game → Settings window: opens (evidence: `src/screens/main_game_screen.py`)
- Main game → Theme: uses (evidence: `src/screens/main_game_screen.py`)
- Main game → Pet theme: uses (evidence: `src/screens/main_game_screen.py`)
- Main game → Rounded widgets: uses (evidence: `src/screens/main_game_screen.py`)
- Settings window → Theme: uses (evidence: `src/ui/unified_settings.py`)
- Task planner → Rounded widgets: uses (evidence: `src/ui/tasks_panel.py`)
