# jacob-sauve/ripper architecture

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

- Interactive diagram: https://gitdiagram.com/jacob-sauve/ripper
- Repository: https://github.com/jacob-sauve/ripper

## Overview

This repository implements software for the Ripper EV3/BrickPi robot. Its primary workflow loads a command script, parses recognized commands, queues them for the multiprocessing controller, and coordinates sensor-guided motion and actuator behavior until the touch sensor triggers shutdown. The excerpts show the entry point, parser, hardware adapter, and portions of the controller; some command internals and worker wiring are therefore represented only where the excerpts support them. Remote brick control is a separate optional capability.

Main entry points: [`src/main.py`](https://github.com/jacob-sauve/ripper/blob/main/src/main.py) (Robot entry), [`src/multi_process_drive.py`](https://github.com/jacob-sauve/ripper/blob/main/src/multi_process_drive.py) (Megamind), [`src/command_parser.py`](https://github.com/jacob-sauve/ripper/blob/main/src/command_parser.py) (Command parser), [`utils/remote.py`](https://github.com/jacob-sauve/ripper/blob/main/utils/remote.py) (Remote brick client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Command control"]
  node_commands["Command script<br/>[commands.txt]"]
  node_entry["Robot entry<br/>[main.py]"]
  node_parser["Command parser<br/>[command_parser.py]"]
end

subgraph group_robot["Robot runtime"]
  node_controller["Megamind"]
  node_workers["Sensor and motor workers"]
  node_brick["BrickPi adapter<br/>[brick.py]"]
  node_stop["Touch stop<br/>[brick.py]"]
end

subgraph group_features["Robot features"]
  node_color["Color classification<br/>[colors.py]"]
  node_music["Jingle playback<br/>[musical.py]"]
  node_sound["Audio synthesis<br/>[sound.py]"]
  node_title["Startup titlecard<br/>[titlecard.py]"]
end

subgraph group_remote["Remote control"]
  node_remoteclient["Remote brick client<br/>[remote.py]"]
  node_remoteserver["Remote brick server<br/>[remote.py]"]
  node_rmi["Remote invocation<br/>[rmi.py]"]
end

node_operator(("Operator"))
node_ev3["EV3 robot hardware"]
node_remoteactor(("Remote controller"))

node_operator -->|"edits"| node_commands
node_entry -->|"parses via"| node_parser
node_parser -->|"reads"| node_commands
node_parser -->|"returns commands"| node_entry
node_entry -->|"creates and queues"| node_controller
node_entry -->|"polls"| node_stop
node_entry -->|"shows"| node_title
node_entry -->|"shuts down"| node_controller
node_controller -->|"dispatches work"| node_workers
node_workers -->|"reads sensors and drives"| node_brick
node_brick -->|"accesses"| node_ev3
node_stop -->|"reads touch input"| node_ev3
node_controller -->|"invokes jingles"| node_music
node_music -->|"builds and plays"| node_sound
node_remoteactor -.->|"controls remotely"| node_remoteclient
node_remoteclient -.->|"uses"| node_rmi
node_remoteserver -.->|"uses"| node_rmi
node_remoteserver -.->|"registers brick"| node_brick
node_remoteclient -.->|"controls through brick"| node_ev3

click node_commands "https://github.com/jacob-sauve/ripper/blob/main/src/commands.txt"
click node_entry "https://github.com/jacob-sauve/ripper/blob/main/src/main.py"
click node_parser "https://github.com/jacob-sauve/ripper/blob/main/src/command_parser.py"
click node_controller "https://github.com/jacob-sauve/ripper/blob/main/src/multi_process_drive.py"
click node_workers "https://github.com/jacob-sauve/ripper/blob/main/src/multi_process_drive.py"
click node_brick "https://github.com/jacob-sauve/ripper/blob/main/utils/brick.py"
click node_stop "https://github.com/jacob-sauve/ripper/blob/main/utils/brick.py"
click node_color "https://github.com/jacob-sauve/ripper/blob/main/src/colors.py"
click node_music "https://github.com/jacob-sauve/ripper/blob/main/src/musical.py"
click node_sound "https://github.com/jacob-sauve/ripper/blob/main/utils/sound.py"
click node_title "https://github.com/jacob-sauve/ripper/blob/main/src/titlecard.py"
click node_remoteclient "https://github.com/jacob-sauve/ripper/blob/main/utils/remote.py"
click node_remoteserver "https://github.com/jacob-sauve/ripper/blob/main/utils/remote.py"
click node_rmi "https://github.com/jacob-sauve/ripper/blob/main/utils/rmi.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_commands,node_entry,node_parser toneBlue
class node_controller,node_workers,node_brick,node_stop toneAmber
class node_color,node_music,node_sound,node_title toneMint
class node_remoteclient,node_remoteserver,node_rmi toneRose
class node_operator,node_ev3,node_remoteactor toneIndigo
```

## Components

### Command control

- [Command script](https://github.com/jacob-sauve/ripper/blob/main/src/commands.txt): `src/commands.txt`
- [Robot entry](https://github.com/jacob-sauve/ripper/blob/main/src/main.py): `src/main.py`
- [Command parser](https://github.com/jacob-sauve/ripper/blob/main/src/command_parser.py): `src/command_parser.py`

### Robot runtime

- [Megamind](https://github.com/jacob-sauve/ripper/blob/main/src/multi_process_drive.py): `src/multi_process_drive.py`
- [Sensor and motor workers](https://github.com/jacob-sauve/ripper/blob/main/src/multi_process_drive.py): `src/multi_process_drive.py`
- [BrickPi adapter](https://github.com/jacob-sauve/ripper/blob/main/utils/brick.py): `utils/brick.py`
- [Touch stop](https://github.com/jacob-sauve/ripper/blob/main/utils/brick.py): `utils/brick.py`

### Robot features

- [Color classification](https://github.com/jacob-sauve/ripper/blob/main/src/colors.py): `src/colors.py`
- [Jingle playback](https://github.com/jacob-sauve/ripper/blob/main/src/musical.py): `src/musical.py`
- [Audio synthesis](https://github.com/jacob-sauve/ripper/blob/main/utils/sound.py): `utils/sound.py`
- [Startup titlecard](https://github.com/jacob-sauve/ripper/blob/main/src/titlecard.py): `src/titlecard.py`

### Remote control

- [Remote brick client](https://github.com/jacob-sauve/ripper/blob/main/utils/remote.py): `utils/remote.py`
- [Remote brick server](https://github.com/jacob-sauve/ripper/blob/main/utils/remote.py): `utils/remote.py`
- [Remote invocation](https://github.com/jacob-sauve/ripper/blob/main/utils/rmi.py): `utils/rmi.py`

### Other components

- **Operator**
- **EV3 robot hardware**
- **Remote controller**

## Connections

- Operator → Command script: edits
- Robot entry → Command parser: parses via
- Command parser → Command script: reads
- Command parser → Robot entry: returns commands
- Robot entry → Megamind: creates and queues
- Robot entry → Touch stop: polls
- Robot entry → Startup titlecard: shows
- Robot entry → Megamind: shuts down
- Megamind → Sensor and motor workers: dispatches work
- Sensor and motor workers → BrickPi adapter: reads sensors and drives
- BrickPi adapter → EV3 robot hardware: accesses
- Touch stop → EV3 robot hardware: reads touch input
- Megamind → Jingle playback: invokes jingles
- Jingle playback → Audio synthesis: builds and plays
- Remote controller → Remote brick client: controls remotely
- Remote brick client → Remote invocation: uses
- Remote brick server → Remote invocation: uses
- Remote brick server → BrickPi adapter: registers brick
- Remote brick client → EV3 robot hardware: controls through brick