# nur-srijan/timeloop-terminal architecture

> Architecture diagram of the GitHub repository nur-srijan/timeloop-terminal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nur-srijan/timeloop-terminal
- Repository: https://github.com/nur-srijan/timeloop-terminal

## Overview

##### Project type and purpose
- This is an open-source CLI tool written in Rust, called “TimeLoop Terminal.”
- It provides a super-intelligent terminal emulator that records every keystroke, file change, and shell state, then lets you rewind, replay, and branch your terminal history.

##### File structure
- Top-level files:
- Cargo.toml (Rust project manifest)
- README.md (project description, usage, architecture)
- CONCURRENT_ACCESS_FIX.md, demo_file_watching.md (documentation)
- src/ directory: each .rs file maps to a core component:
- main.rs: CLI entry point & command dispatcher
- lib.rs: public API and shared types
- error.rs: error definitions and handling
- events.rs: event definitions & recording logic (KeyPress, Command, FileChange, TerminalState, SessionMetadata)
- session.rs: session lifecycle (start, stop, metadata)
- terminal.rs: the terminal emulator integration (crossterm calls)
- file_watcher.rs: filesystem monitoring (notify, ignore patterns)
- storage.rs: persistent storage abstraction over sled DB
- replay.rs: replay engine (playback speed, time ranges, visualization hooks)
- branch.rs: branch & merge operations on session timelines
- replay.rs and branch.rs reference storage and events

##### README for additional insights
- Core components are explicitly listed: Event Recorder, Storage Engine (sled), Replay Engine, Branch Manager, File Watcher, Terminal Emulator
- It describes event sourcing, session analytics, and the use cases (debugging, tutorials, experimentation)
- It mentions configuration (ignored file patterns, storage location)

##### Additional notes
- Important flows (e.g., “append events,” “read events,” “merge branch”)
- Provide side-notes on configuration (ignored patterns, storage paths) to capture deployment details

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Layer"]:::api
    API["Public Library API"]:::api
    Terminal["Terminal Emulator"]:::infra
    FileWatcher["File Watcher"]:::infra
    Recorder["Event Recorder"]:::core
    Session["Session Lifecycle"]:::core
    Storage["Storage Engine"]:::infra
    Replay["Replay Engine"]:::core
    Branch["Branch Manager"]:::core
    Error["Error Handler"]:::error
    ExternalFS["Local File System"]:::external
    Crossterm["crossterm"]:::external
    SledDB["sled DB"]:::external
    UserShell["User Shell"]:::external

    %% CLI to API
    CLI -->|"commands (start/stop/list/replay/branch)"| API

    %% API routes to domain components
    API --> Recorder
    API --> Session
    API --> Replay
    API --> Branch

    %% User input flow
    UserShell -->|"keystroke/input"| Terminal
    Terminal -->|"crossterm calls"| Crossterm
    Terminal -->|"emit events"| Recorder

    %% File watcher flow
    ExternalFS --> FileWatcher
    FileWatcher -->|"file change events"| Recorder

    %% Recording to storage
    Recorder -->|"append events"| Storage
    Session -->|"session metadata"| Storage

    %% Replay flow
    Replay -->|"read events"| Storage
    Replay -->|"render playback"| Terminal

    %% Branch management
    Branch -->|"read/write branch metadata"| Storage
    Storage -->|"branch data"| Branch

    %% Error handling cross-cutting
    Recorder -->|"errors"| Error
    Session -->|"errors"| Error
    Terminal -->|"errors"| Error
    FileWatcher -->|"errors"| Error
    Storage -->|"errors"| Error
    Replay -->|"errors"| Error
    Branch -->|"errors"| Error
    API -->|"errors"| Error
    CLI -->|"errors"| Error

    %% External DB integration
    Storage --> SledDB

    %% Legend grouping (not clickable)
    classDef core fill:#fbb,stroke:#333,stroke-width:1px
    classDef infra fill:#bbf,stroke:#333,stroke-width:1px
    classDef api fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef error fill:#f99,stroke:#333,stroke-width:1px

    %% Click events
    click CLI "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/main.rs"
    click API "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/lib.rs"
    click Error "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/error.rs"
    click Recorder "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/events.rs"
    click Session "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/session.rs"
    click FileWatcher "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/file_watcher.rs"
    click Storage "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/storage.rs"
    click Replay "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/replay.rs"
    click Branch "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/branch.rs"
    click Terminal "https://github.com/nur-srijan/timeloop-terminal/blob/main/src/terminal.rs"
```
