# arjan-git1/codium architecture

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

- Interactive diagram: https://gitdiagram.com/arjan-git1/codium
- Repository: https://github.com/arjan-git1/codium

## Overview

1. **What this repo is**
   - Codium is a single Rust binary for a terminal-based, Vim-inspired code editor. The current architecture is centered on interactive text editing in the terminal; the README also signals a future GUI, but that is not part of the present design.

2. **Crate layout and entrypoint**
   - The active application code lives under `src/`, with `src/main.rs` as the startup point.
   - The crate is organized into small modules instead of one monolith, which makes the editor logic easier to diagram as separate input, mode, command, and text-storage layers.
   - There is also a top-level `editor.rs` in the repository root, but the main Rust source tree is clearly `src/`.

3. **Editor core**
   - `src/editor.rs` is the central orchestration layer: it is the most likely place where the editor state, buffer, cursor, and rendering/update cycle are coordinated.
   - This layer sits between user input and the underlying text model, translating high-level editor actions into buffer mutations and screen updates.

4. **Text model / storage**
   - `src/piecetable.rs` is the key data-structure module.
   - A piece table is an editing-oriented text representation optimized for insert/delete-heavy workflows, which suggests the editor is built around incremental text mutation rather than rewriting the whole file each time.
   - This is the primary persistence/edit buffer boundary in the system.

5. **Mode system**
   - `src/mode.rs` captures the Vim-like editing model: different modes likely gate what a key press means.
   - This module is an architectural boundary because the same input can produce different behavior depending on whether the editor is in normal, insert, or command-like states.

6. **Key handling**
   - `src/keys.rs` likely normalizes raw keyboard events into editor-relevant key definitions.
   - This layer sits between terminal input and the command/mode logic, turning low-level key events into a consistent internal representation.

7. **Input processing**
   - `src/input.rs` is the bridge from the terminal runtime into the editor’s event loop.
   - It likely collects keystrokes and dispatches them onward, making it the ingestion point for user interaction.

8. **Command layer**
   - `src/commands.rs` holds the executable editor actions: movement, insertion, deletion, file-related actions, and other mode-driven behaviors.
   - Architecturally, this module is the action catalog that the mode and key system map into.

9. **Runtime data flow**
   - The main loop is conceptually: terminal input arrives → input/key translation happens → current mode interprets the key → a command is selected/executed → the editor mutates the piece table and internal state → the UI is refreshed in the terminal.
   - This creates a clear separation between event handling, state transitions, and text mutation.

10. **External boundaries**
   - The only clearly implied runtime dependency is the terminal environment; there are no visible web, database, or network components in this repo snapshot.
   - `Cargo.toml` and `Cargo.lock` show this is a standard Rust application with dependency-managed builds.

11. **Repository signals**
   - `text.txt` is likely a sample input file or editor test target, useful for understanding how the editor opens or manipulates content.
   - The presence of a Vim-inspired mode system and piece-table storage strongly suggests the architecture is optimized for interactive editing rather than batch text processing.

Main entry points: [`src/editor.rs`](https://github.com/arjan-git1/codium/blob/main/src/editor.rs) (Editor), [`src/main.rs`](https://github.com/arjan-git1/codium/blob/main/src/main.rs) (Main), [`src/input.rs`](https://github.com/arjan-git1/codium/blob/main/src/input.rs) (Input), [`src/mode.rs`](https://github.com/arjan-git1/codium/blob/main/src/mode.rs) (Mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_user(("User<br/>external actor"))
  node_terminal["Terminal<br/>runtime host"]
  node_main["Main<br/>binary entrypoint<br/>[main.rs]"]
  node_build["Cargo<br/>rust build<br/>[Cargo.toml]"]
  node_lockfile["Lockfile<br/>dependency lock<br/>[Cargo.lock]"]
  node_readme["README<br/>project docs<br/>[README.md]"]
end

subgraph group_control["Control flow"]
  node_input["Input<br/>event bridge<br/>[input.rs]"]
  node_keys["Keys<br/>key normalization<br/>[keys.rs]"]
  node_mode{{"Mode<br/>vim state<br/>[mode.rs]"}}
  node_commands["Commands<br/>action catalog<br/>[commands.rs]"]
end

subgraph group_core["Editor core"]
  node_editor["Editor<br/>orchestrator<br/>[editor.rs]"]
end

subgraph group_storage["Text model"]
  node_piecetable[("Piece table<br/>text buffer<br/>[piecetable.rs]")]
  node_files[("File system<br/>persistence boundary")]
  node_textfile["Sample text<br/>content fixture<br/>[text.txt]"]
end

node_user -->|"types"| node_terminal
node_terminal -->|"events"| node_input
node_input -->|"normalizes"| node_keys
node_keys -->|"interprets"| node_mode
node_mode -->|"selects"| node_commands
node_commands -->|"mutates"| node_editor
node_editor -->|"edits"| node_piecetable
node_piecetable -->|"persists"| node_files
node_main -->|"starts"| node_editor
node_editor -->|"drives"| node_input
node_editor -->|"tracks"| node_mode
node_editor -->|"dispatches"| node_commands
node_terminal -->|"renders"| node_editor
node_textfile -->|"sample input"| node_editor
node_build -->|"builds"| node_main
node_lockfile -->|"pins"| node_build
node_readme -->|"documents"| node_main

click node_main "https://github.com/arjan-git1/codium/blob/main/src/main.rs"
click node_input "https://github.com/arjan-git1/codium/blob/main/src/input.rs"
click node_keys "https://github.com/arjan-git1/codium/blob/main/src/keys.rs"
click node_mode "https://github.com/arjan-git1/codium/blob/main/src/mode.rs"
click node_commands "https://github.com/arjan-git1/codium/blob/main/src/commands.rs"
click node_editor "https://github.com/arjan-git1/codium/blob/main/src/editor.rs"
click node_piecetable "https://github.com/arjan-git1/codium/blob/main/src/piecetable.rs"
click node_textfile "https://github.com/arjan-git1/codium/blob/main/text.txt"
click node_build "https://github.com/arjan-git1/codium/blob/main/Cargo.toml"
click node_lockfile "https://github.com/arjan-git1/codium/blob/main/Cargo.lock"
click node_readme "https://github.com/arjan-git1/codium/blob/main/README.md"

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_user,node_terminal,node_main,node_build,node_lockfile,node_readme toneBlue
class node_input,node_keys,node_mode,node_commands toneAmber
class node_editor toneMint
class node_piecetable,node_files,node_textfile toneRose
```

## Components

### Runtime

Terminal interaction and application startup

- **User**: external actor · Person typing into the editor
- **Terminal**: runtime host · Terminal environment that delivers key events and displays output
- [Main](https://github.com/arjan-git1/codium/blob/main/src/main.rs): binary entrypoint · Program startup and top-level event loop bootstrap · `src/main.rs`
- [Cargo](https://github.com/arjan-git1/codium/blob/main/Cargo.toml): rust build · Dependency-managed Rust package and build metadata · `Cargo.toml`
- [Lockfile](https://github.com/arjan-git1/codium/blob/main/Cargo.lock): dependency lock · Pinned dependency resolution for reproducible builds · `Cargo.lock`
- [README](https://github.com/arjan-git1/codium/blob/main/README.md): project docs · Repository overview and usage notes · `README.md`

### Control flow

Input, keys, modes, and command dispatch

- [Input](https://github.com/arjan-git1/codium/blob/main/src/input.rs): event bridge · Collects terminal input and forwards editor events · `src/input.rs`
- [Keys](https://github.com/arjan-git1/codium/blob/main/src/keys.rs): key normalization · Translates raw key events into editor-facing key representations · `src/keys.rs`
- [Mode](https://github.com/arjan-git1/codium/blob/main/src/mode.rs): vim state · Selects behavior based on the current editing mode · `src/mode.rs`
- [Commands](https://github.com/arjan-git1/codium/blob/main/src/commands.rs): action catalog · Movement, edit, and mode-driven editor actions · `src/commands.rs`

### Editor core

State orchestration and screen update cycle

- [Editor](https://github.com/arjan-git1/codium/blob/main/src/editor.rs): orchestrator · Coordinates editor state, cursor, commands, and redraws · `src/editor.rs`

### Text model

Piece-table text storage and file boundary

- [Piece table](https://github.com/arjan-git1/codium/blob/main/src/piecetable.rs): text buffer · Incremental text storage optimized for inserts and deletes · `src/piecetable.rs`
- **File system**: persistence boundary · Underlying disk-backed file access for opening and saving text
- [Sample text](https://github.com/arjan-git1/codium/blob/main/text.txt): content fixture · Example text content used to exercise the editor · `text.txt`

## Connections

- User → Terminal: types · User enters keystrokes into the terminal
- Terminal → Input: events · Terminal input is ingested by the runtime bridge
- Input → Keys: normalizes · Raw key events are converted into internal key forms
- Keys → Mode: interprets · Keys are interpreted according to the active mode
- Mode → Commands: selects · Mode chooses which editor command should run
- Commands → Editor: mutates · Commands apply changes through the editor coordinator
- Editor → Piece table: edits · Editor updates the piece table buffer
- Piece table → File system: persists · Text model reads from and writes to disk-backed files
- Main → Editor: starts · Entrypoint constructs and runs the editor
- Editor → Input: drives · Editor loop requests and processes input
- Editor → Mode: tracks · Editor keeps the current editing mode in sync
- Editor → Commands: dispatches · Editor routes interpreted actions to command handlers
- Terminal → Editor: renders · Editor updates are shown back in the terminal
- Sample text → Editor: sample input · Repository example content can be opened by the editor
- Cargo → Main: builds · Cargo builds the binary entrypoint
- Lockfile → Cargo: pins · Lockfile freezes dependency versions
- README → Main: documents · README describes the application and its usage
