# bai-zihan/terrarium-simulation architecture

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

- Interactive diagram: https://gitdiagram.com/bai-zihan/terrarium-simulation
- Repository: https://github.com/bai-zihan/terrarium-simulation

## Overview

Terrarium Simulation is a terminal-first game for designing closed terrariums and observing their simulated ecosystems. The main workflow is to issue CLI commands to configure a bottle’s container, substrate, placement, hardscape, plants, and animals; sealing starts hourly survival simulation, which players can inspect, pause, or resume. The CLI also supports batch runs and saving or loading bottles. The model excerpts show simulation and ecology calculations, while README capabilities fill in setup stages whose implementations were not sampled; those internals remain grouped conservatively.

Main entry points: [`terrarium/cli.py`](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py) (Command interface), [`terrarium/model.py`](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py) (Hourly survival), [`terrarium/render.py`](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/render.py) (Terminal displays)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["CLI interaction"]
  node_cli["Command interface<br/>[cli.py]"]
end

subgraph group_crafting["Bottle crafting"]
  node_model["Terrarium model<br/>[model.py]"]
  node_container["Container setup<br/>[model.py]"]
  node_substrate["Substrate and moisture<br/>[model.py]"]
  node_placement["Light and placement<br/>[model.py]"]
  node_hardscape["Hardscape placement<br/>[model.py]"]
  node_life["Plants and animals<br/>[model.py]"]
end

subgraph group_simulation["Ecosystem simulation"]
  node_environment["Environment cycles<br/>[model.py]"]
  node_ecology["Ecological responses<br/>[model.py]"]
  node_survival["Hourly survival<br/>[model.py]"]
end

subgraph group_observation["Observation and management"]
  node_manager["Bottle manager<br/>[cli.py]"]
  node_reports["Observation reports<br/>[cli.py]"]
  node_render["Terminal displays<br/>[render.py]"]
  node_storage["Bottle files<br/>[cli.py]"]
end

node_player(("Player"))
node_filesystem[("Local files")]

node_player -->|"issues commands"| node_cli
node_cli -->|"configures"| node_container
node_cli -->|"configures"| node_substrate
node_cli -->|"configures"| node_placement
node_cli -->|"places"| node_hardscape
node_cli -->|"adds and tends"| node_life
node_cli -->|"manages bottles"| node_manager
node_cli -->|"runs ticks"| node_survival
node_cli -->|"requests views"| node_render
node_manager -->|"advances bottles"| node_survival
node_manager -->|"collects changes"| node_reports
node_survival -->|"updates conditions"| node_environment
node_survival -->|"updates organisms"| node_ecology
node_render -->|"reads state"| node_model
node_cli -->|"loads and saves"| node_storage
node_storage -->|"reads and writes"| node_filesystem
node_reports -->|"prints observations"| node_cli
node_render -->|"returns display"| node_cli

click node_cli "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py"
click node_model "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_container "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_substrate "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_placement "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_hardscape "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_life "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_environment "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_ecology "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_survival "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py"
click node_manager "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py"
click node_reports "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py"
click node_render "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/render.py"
click node_storage "https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.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_cli toneBlue
class node_model,node_container,node_substrate,node_placement,node_hardscape,node_life,node_filesystem toneAmber
class node_environment,node_ecology,node_survival toneMint
class node_manager,node_reports,node_render,node_storage toneRose
class node_player toneIndigo
```

## Components

### CLI interaction

- [Command interface](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py): `terrarium/cli.py`

### Bottle crafting

- [Terrarium model](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Container setup](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Substrate and moisture](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Light and placement](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Hardscape placement](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Plants and animals](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`

### Ecosystem simulation

- [Environment cycles](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Ecological responses](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`
- [Hourly survival](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/model.py): `terrarium/model.py`

### Observation and management

- [Bottle manager](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py): `terrarium/cli.py`
- [Observation reports](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py): `terrarium/cli.py`
- [Terminal displays](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/render.py): `terrarium/render.py`
- [Bottle files](https://github.com/bai-zihan/terrarium-simulation/blob/main/terrarium/cli.py): `terrarium/cli.py`

### Other components

- **Player**
- **Local files**

## Connections

- Player → Command interface: issues commands
- Command interface → Container setup: configures
- Command interface → Substrate and moisture: configures
- Command interface → Light and placement: configures
- Command interface → Hardscape placement: places
- Command interface → Plants and animals: adds and tends
- Command interface → Bottle manager: manages bottles
- Command interface → Hourly survival: runs ticks
- Command interface → Terminal displays: requests views
- Bottle manager → Hourly survival: advances bottles
- Bottle manager → Observation reports: collects changes
- Hourly survival → Environment cycles: updates conditions
- Hourly survival → Ecological responses: updates organisms
- Terminal displays → Terrarium model: reads state
- Command interface → Bottle files: loads and saves
- Bottle files → Local files: reads and writes
- Observation reports → Command interface: prints observations
- Terminal displays → Command interface: returns display