# titasmallick/petrichip architecture

> Architecture diagram of the GitHub repository titasmallick/petrichip, 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/titasmallick/petrichip
- Repository: https://github.com/titasmallick/petrichip

## Overview

Silicon Petri Dish is an artificial-life simulation project with separate ESP32, Node.js, and Python-assisted implementations. The principal workflow is organisms sensing an environment, evolving and interacting under simulation rules, then exposing live state and logged population metrics to users. The v4 branch adds a PyTorch observer that evaluates telemetry and sends interventions. The Node.js engines also document analytical observation through Gemini. Several capabilities are documented but their implementation details were not sampled; the graph limits those relationships to documented claims.

Main entry points: [`petriChipNode/public`](https://github.com/titasmallick/petrichip/tree/master/petriChipNode/public) (Node Dashboards), [`petriChipNode/server_v4.js`](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v4.js) (AI God Engine), [`petriChipNode/evolution_v2_log.csv`](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/evolution_v2_log.csv) (Evolution CSV Logs), [`petriChipNode/server.js`](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server.js) (NEAT Lite Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engines["Simulation Engines"]
  node_neat_engine["NEAT Lite Engine<br/>[server.js]"]
  node_v2_engine["Biogeochemical Engine<br/>[server_v2.js]"]
  node_v3_engine["Ecosystem Engine V3<br/>[server_v3.js]"]
  node_v4_engine["AI God Engine<br/>[server_v4.js]"]
  node_simulation_rules["Evolution and Ecology<br/>[server_v4.js]"]
end

subgraph group_interfaces["User Interfaces"]
  node_node_dashboard["Node Dashboards"]
  node_history_api["History API<br/>[server.js]"]
end

subgraph group_observation["Observation and Control"]
  node_csv_logs[("Evolution CSV Logs")]
  node_gemini["Gemini Observer"]
  node_pytorch_agent["PyTorch Observer"]
  node_esp_logger["ESP32 Logger<br/>[esp32_logger.js]"]
  node_esp_logs[("ESP32 CSV Logs")]
end

subgraph group_edge["ESP32 Deployment"]
  node_esp32_firmware["ESP32 Simulation<br/>[BionotesESP32.ino]"]
  node_esp32_dashboard["ESP32 Dashboard<br/>[BionotesESP32.ino]"]
end

node_user(("Simulation User"))

node_user -->|"views"| node_node_dashboard
node_node_dashboard -.->|"displays simulation"| node_neat_engine
node_node_dashboard -.->|"displays simulation"| node_v2_engine
node_node_dashboard -.->|"displays simulation"| node_v3_engine
node_node_dashboard -->|"displays simulation"| node_v4_engine
node_neat_engine -.->|"runs evolution"| node_simulation_rules
node_v2_engine -.->|"runs ecology"| node_simulation_rules
node_v3_engine -.->|"runs ecology"| node_simulation_rules
node_v4_engine -->|"runs evolution"| node_simulation_rules
node_neat_engine -->|"appends metrics"| node_csv_logs
node_v2_engine -->|"appends metrics"| node_csv_logs
node_v3_engine -->|"appends metrics"| node_csv_logs
node_v4_engine -->|"appends metrics"| node_csv_logs
node_neat_engine -->|"requests analysis"| node_gemini
node_v2_engine -->|"requests analysis"| node_gemini
node_v4_engine -->|"streams telemetry"| node_pytorch_agent
node_pytorch_agent -->|"sends interventions"| node_v4_engine
node_user -->|"views"| node_esp32_dashboard
node_esp32_firmware -->|"serves dashboard"| node_esp32_dashboard
node_esp_logger -.->|"polls state"| node_esp32_firmware
node_esp_logger -->|"appends metrics"| node_esp_logs
node_node_dashboard -.->|"requests history"| node_history_api
node_history_api -->|"reads history"| node_csv_logs

click node_neat_engine "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server.js"
click node_v2_engine "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v2.js"
click node_v3_engine "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v3.js"
click node_v4_engine "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v4.js"
click node_simulation_rules "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v4.js"
click node_node_dashboard "https://github.com/titasmallick/petrichip/tree/master/petriChipNode/public"
click node_history_api "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server.js"
click node_csv_logs "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/evolution_v2_log.csv"
click node_pytorch_agent "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/pytorch_observer.py"
click node_esp32_firmware "https://github.com/titasmallick/petrichip/blob/master/BionotesESP32/BionotesESP32.ino"
click node_esp32_dashboard "https://github.com/titasmallick/petrichip/blob/master/BionotesESP32/BionotesESP32.ino"
click node_esp_logger "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/esp32_logger.js"
click node_esp_logs "https://github.com/titasmallick/petrichip/blob/master/petriChipNode/esp32_evolution_log.csv"

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_neat_engine,node_v2_engine,node_v3_engine,node_v4_engine,node_simulation_rules,node_user toneBlue
class node_node_dashboard,node_history_api toneAmber
class node_csv_logs,node_gemini,node_pytorch_agent,node_esp_logger,node_esp_logs toneMint
class node_esp32_firmware,node_esp32_dashboard toneRose
```

## Components

### Simulation Engines

- [NEAT Lite Engine](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server.js): `petriChipNode/server.js`
- [Biogeochemical Engine](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v2.js): `petriChipNode/server_v2.js`
- [Ecosystem Engine V3](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v3.js): `petriChipNode/server_v3.js`
- [AI God Engine](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v4.js): `petriChipNode/server_v4.js`
- [Evolution and Ecology](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server_v4.js): `petriChipNode/server_v4.js`

### User Interfaces

- [Node Dashboards](https://github.com/titasmallick/petrichip/tree/master/petriChipNode/public): `petriChipNode/public`
- [History API](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/server.js): `petriChipNode/server.js`

### Observation and Control

- [Evolution CSV Logs](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/evolution_v2_log.csv): `petriChipNode/evolution_v2_log.csv`
- **Gemini Observer**
- [PyTorch Observer](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/pytorch_observer.py): `petriChipNode/pytorch_observer.py`
- [ESP32 Logger](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/esp32_logger.js): `petriChipNode/esp32_logger.js`
- [ESP32 CSV Logs](https://github.com/titasmallick/petrichip/blob/master/petriChipNode/esp32_evolution_log.csv): `petriChipNode/esp32_evolution_log.csv`

### ESP32 Deployment

- [ESP32 Simulation](https://github.com/titasmallick/petrichip/blob/master/BionotesESP32/BionotesESP32.ino): `BionotesESP32/BionotesESP32.ino`
- [ESP32 Dashboard](https://github.com/titasmallick/petrichip/blob/master/BionotesESP32/BionotesESP32.ino): `BionotesESP32/BionotesESP32.ino`

### Other components

- **Simulation User**

## Connections

- Simulation User → Node Dashboards: views (evidence: `README.md`)
- Node Dashboards → NEAT Lite Engine: displays simulation (evidence: `README.md`)
- Node Dashboards → Biogeochemical Engine: displays simulation (evidence: `README.md`)
- Node Dashboards → Ecosystem Engine V3: displays simulation (evidence: `README.md`)
- Node Dashboards → AI God Engine: displays simulation (evidence: `petriChipNode/server_v4.js`)
- NEAT Lite Engine → Evolution and Ecology: runs evolution (evidence: `README.md`)
- Biogeochemical Engine → Evolution and Ecology: runs ecology (evidence: `README.md`)
- Ecosystem Engine V3 → Evolution and Ecology: runs ecology (evidence: `README.md`)
- AI God Engine → Evolution and Ecology: runs evolution (evidence: `petriChipNode/server_v4.js`)
- NEAT Lite Engine → Evolution CSV Logs: appends metrics (evidence: `petriChipNode/server.js`)
- Biogeochemical Engine → Evolution CSV Logs: appends metrics (evidence: `petriChipNode/server_v2.js`)
- Ecosystem Engine V3 → Evolution CSV Logs: appends metrics (evidence: `petriChipNode/server_v3.js`)
- AI God Engine → Evolution CSV Logs: appends metrics (evidence: `petriChipNode/server_v4.js`)
- NEAT Lite Engine → Gemini Observer: requests analysis (evidence: `petriChipNode/server.js`)
- Biogeochemical Engine → Gemini Observer: requests analysis (evidence: `petriChipNode/server_v2.js`)
- AI God Engine → PyTorch Observer: streams telemetry (evidence: `README.md`)
- PyTorch Observer → AI God Engine: sends interventions (evidence: `README.md`)
- Simulation User → ESP32 Dashboard: views (evidence: `README.md`)
- ESP32 Simulation → ESP32 Dashboard: serves dashboard (evidence: `README.md`)
- ESP32 Logger → ESP32 Simulation: polls state
- ESP32 Logger → ESP32 CSV Logs: appends metrics (evidence: `petriChipNode/esp32_logger.js`)
- Node Dashboards → History API: requests history
- History API → Evolution CSV Logs: reads history (evidence: `petriChipNode/server.js`)
