# bammyverylazy/compro_group_proj architecture

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

- Interactive diagram: https://gitdiagram.com/bammyverylazy/compro_group_proj
- Repository: https://github.com/bammyverylazy/compro_group_proj

## Overview

CPE Egg Hatch is a Flet study-and-hatching game. Its main loop runs from the landing page to a lobby, through a timed subject study session, then to hatching or a failed-session result and back to the lobby. The service layer manages sessions, rarity rolls, and pet ownership; the store supplies repositories and save-file persistence. The README also documents room play, a species dex, history, and analytics, though Phase 1 marks some of those as later-phase capabilities. Links for unsampled views and services rely on the README or SOURCE INDEX references, not inspected implementations.

Main entry points: [`ui/core/app_context.py`](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/core/app_context.py) (App context), [`ui/core/navigator.py`](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/core/navigator.py) (Screen navigation), [`app/services/focus_service.py`](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/focus_service.py) (Focus sessions), [`app/services/room_service.py`](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/room_service.py) (Group rooms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["User interface"]
  node_navigation["Screen navigation<br/>[navigator.py]"]
  node_landing["Landing and setup<br/>[landing_view.py]"]
  node_lobby["Lobby and pets<br/>[lobby_view.py]"]
  node_focusui["Focus screen<br/>[focus_view.py]"]
  node_hatchui["Hatch and result<br/>[hatch_view.py]"]
  node_historyui["History view<br/>[history_view.py]"]
  node_dexui["Dex view<br/>[dex_view.py]"]
end

subgraph group_services["Game services"]
  node_focus["Focus sessions<br/>[focus_service.py]"]
  node_room["Group rooms<br/>[room_service.py]"]
  node_hatch["Hatch service<br/>[hatch_service.py]"]
  node_analytics["History analytics"]
  node_dex["Species dex<br/>[dex_service.py]"]
end

subgraph group_domain["Game domain"]
  node_session["Study session<br/>[study_session.py]"]
  node_odds["Tier odds<br/>[tier_odds_table.py]"]
  node_species["Species catalog<br/>[species.py]"]
  node_roommodel["Room model<br/>[group_room.py]"]
  node_dto["Transfer objects<br/>[dto.py]"]
  node_enums["Game statuses<br/>[enums.py]"]
end

subgraph group_storage["Persistence"]
  node_store[("Game store<br/>[game_store.py]")]
  node_repositories["Entity repositories<br/>[repositories.py]"]
  node_save["Save file<br/>[save_file.py]"]
end

subgraph group_support["Runtime support"]
  node_entry["App entry<br/>[main.py]"]
  node_context["App context<br/>[app_context.py]"]
  node_clock["Study clock<br/>[clock.py]"]
  node_config["Settings<br/>[config.py]"]
end

node_user(("Player"))

node_user -->|"opens app"| node_entry
node_entry -->|"creates context"| node_context
node_context -->|"opens store"| node_store
node_context -->|"creates clock"| node_clock
node_context -->|"creates service"| node_focus
node_context -->|"creates service"| node_hatch
node_context -->|"creates service"| node_room
node_context -->|"creates service"| node_analytics
node_context -->|"creates service"| node_dex
node_context -->|"creates navigator"| node_navigation
node_navigation -->|"routes to"| node_landing
node_navigation -->|"routes to"| node_lobby
node_navigation -->|"routes to"| node_focusui
node_navigation -->|"routes to"| node_hatchui
node_navigation -->|"routes to"| node_historyui
node_navigation -->|"routes to"| node_dexui
node_user -->|"starts game"| node_landing
node_landing -->|"starts focus flow"| node_lobby
node_lobby -->|"starts study"| node_focusui
node_focusui -->|"uses services"| node_context
node_focus -->|"reads and saves"| node_store
node_focus -->|"measures time"| node_clock
node_focus -->|"creates and stops"| node_session
node_focus -->|"gets odds"| node_odds
node_focus -->|"returns results"| node_dto
node_store -->|"owns repositories"| node_repositories
node_store -->|"loads and writes"| node_save
node_room -->|"requests hatching"| node_hatch
node_hatch -->|"reads and saves"| node_store
node_hatch -->|"gets tier odds"| node_odds
node_hatch -->|"selects species"| node_species
node_hatch -->|"returns result"| node_dto
node_room -->|"reads and saves"| node_store
node_room -->|"measures time"| node_clock
node_room -->|"creates and stops"| node_roommodel
node_room -->|"creates and stops"| node_session
node_lobby -.->|"uses services"| node_context
node_hatchui -.->|"uses services"| node_context
node_historyui -.->|"shows reports"| node_analytics
node_dexui -.->|"shows collection"| node_dex
node_room -->|"computes odds"| node_odds
node_context -->|"uses settings"| node_config
node_focus -->|"checks status"| node_enums

click node_entry "https://github.com/bammyverylazy/compro_group_proj/blob/main/main.py"
click node_context "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/core/app_context.py"
click node_navigation "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/core/navigator.py"
click node_landing "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/landing/landing_view.py"
click node_lobby "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/lobby/lobby_view.py"
click node_focusui "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/focus/focus_view.py"
click node_hatchui "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/hatch/hatch_view.py"
click node_historyui "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/result/history_view.py"
click node_dexui "https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/dex/dex_view.py"
click node_focus "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/focus_service.py"
click node_room "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/room_service.py"
click node_hatch "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/hatch_service.py"
click node_analytics "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/analytics_service.py"
click node_dex "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/dex_service.py"
click node_session "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/study_session.py"
click node_odds "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/tier_odds_table.py"
click node_species "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/species.py"
click node_roommodel "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/group_room.py"
click node_dto "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/dto.py"
click node_store "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/data/game_store.py"
click node_repositories "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/data/repositories.py"
click node_save "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/data/save_file.py"
click node_clock "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/core/clock.py"
click node_config "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/config.py"
click node_enums "https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/enums.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_navigation,node_landing,node_lobby,node_focusui,node_hatchui,node_historyui,node_dexui toneBlue
class node_focus,node_room,node_hatch,node_analytics,node_dex toneAmber
class node_session,node_odds,node_species,node_roommodel,node_dto,node_enums toneMint
class node_store,node_repositories,node_save toneRose
class node_entry,node_context,node_clock,node_config,node_user toneIndigo
```

## Components

### User interface

- [Screen navigation](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/core/navigator.py): `ui/core/navigator.py`
- [Landing and setup](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/landing/landing_view.py): `ui/landing/landing_view.py`
- [Lobby and pets](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/lobby/lobby_view.py): `ui/lobby/lobby_view.py`
- [Focus screen](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/focus/focus_view.py): `ui/focus/focus_view.py`
- [Hatch and result](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/hatch/hatch_view.py): `ui/hatch/hatch_view.py`
- [History view](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/result/history_view.py): `ui/result/history_view.py`
- [Dex view](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/dex/dex_view.py): `ui/dex/dex_view.py`

### Game services

- [Focus sessions](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/focus_service.py): `app/services/focus_service.py`
- [Group rooms](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/room_service.py): `app/services/room_service.py`
- [Hatch service](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/hatch_service.py): `app/services/hatch_service.py`
- [History analytics](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/analytics_service.py): `app/services/analytics_service.py`
- [Species dex](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/services/dex_service.py): `app/services/dex_service.py`

### Game domain

- [Study session](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/study_session.py): `app/domain/study_session.py`
- [Tier odds](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/tier_odds_table.py): `app/domain/tier_odds_table.py`
- [Species catalog](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/species.py): `app/domain/species.py`
- [Room model](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/group_room.py): `app/domain/group_room.py`
- [Transfer objects](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/dto.py): `app/dto.py`
- [Game statuses](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/domain/enums.py): `app/domain/enums.py`

### Persistence

- [Game store](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/data/game_store.py): `app/data/game_store.py`
- [Entity repositories](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/data/repositories.py): `app/data/repositories.py`
- [Save file](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/data/save_file.py): `app/data/save_file.py`

### Runtime support

- [App entry](https://github.com/bammyverylazy/compro_group_proj/blob/main/main.py): `main.py`
- [App context](https://github.com/bammyverylazy/compro_group_proj/blob/main/ui/core/app_context.py): `ui/core/app_context.py`
- [Study clock](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/core/clock.py): `app/core/clock.py`
- [Settings](https://github.com/bammyverylazy/compro_group_proj/blob/main/app/config.py): `app/config.py`

### Other components

- **Player**

## Connections

- Player → App entry: opens app
- App entry → App context: creates context (evidence: `main.py`)
- App context → Game store: opens store (evidence: `ui/core/app_context.py`)
- App context → Study clock: creates clock (evidence: `ui/core/app_context.py`)
- App context → Focus sessions: creates service (evidence: `ui/core/app_context.py`)
- App context → Hatch service: creates service (evidence: `ui/core/app_context.py`)
- App context → Group rooms: creates service (evidence: `ui/core/app_context.py`)
- App context → History analytics: creates service (evidence: `ui/core/app_context.py`)
- App context → Species dex: creates service (evidence: `ui/core/app_context.py`)
- App context → Screen navigation: creates navigator (evidence: `ui/core/app_context.py`)
- Screen navigation → Landing and setup: routes to (evidence: `ui/core/navigator.py`)
- Screen navigation → Lobby and pets: routes to (evidence: `ui/core/navigator.py`)
- Screen navigation → Focus screen: routes to (evidence: `ui/core/navigator.py`)
- Screen navigation → Hatch and result: routes to (evidence: `ui/core/navigator.py`)
- Screen navigation → History view: routes to (evidence: `ui/core/navigator.py`)
- Screen navigation → Dex view: routes to (evidence: `ui/core/navigator.py`)
- Player → Landing and setup: starts game
- Landing and setup → Lobby and pets: starts focus flow
- Lobby and pets → Focus screen: starts study
- Focus screen → App context: uses services (evidence: `ui/focus/focus_view.py`)
- Focus sessions → Game store: reads and saves (evidence: `app/services/focus_service.py`)
- Focus sessions → Study clock: measures time (evidence: `app/services/focus_service.py`)
- Focus sessions → Study session: creates and stops (evidence: `app/services/focus_service.py`)
- Focus sessions → Tier odds: gets odds (evidence: `app/services/focus_service.py`)
- Focus sessions → Transfer objects: returns results (evidence: `app/services/focus_service.py`)
- Game store → Entity repositories: owns repositories (evidence: `app/data/game_store.py`)
- Game store → Save file: loads and writes (evidence: `app/data/game_store.py`)
- Group rooms → Hatch service: requests hatching (evidence: `app/services/room_service.py`)
- Hatch service → Game store: reads and saves (evidence: `app/services/hatch_service.py`)
- Hatch service → Tier odds: gets tier odds (evidence: `app/services/hatch_service.py`)
- Hatch service → Species catalog: selects species (evidence: `app/services/hatch_service.py`)
- Hatch service → Transfer objects: returns result (evidence: `app/services/hatch_service.py`)
- Group rooms → Game store: reads and saves (evidence: `app/services/room_service.py`)
- Group rooms → Study clock: measures time (evidence: `app/services/room_service.py`)
- Group rooms → Room model: creates and stops (evidence: `app/services/room_service.py`)
- Group rooms → Study session: creates and stops (evidence: `app/services/room_service.py`)
- Lobby and pets → App context: uses services
- Hatch and result → App context: uses services
- History view → History analytics: shows reports
- Dex view → Species dex: shows collection
- Group rooms → Tier odds: computes odds (evidence: `app/services/room_service.py`)
- App context → Settings: uses settings (evidence: `ui/core/app_context.py`)
- Focus sessions → Game statuses: checks status (evidence: `app/services/focus_service.py`)
