# asciinema/asciinema architecture

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

- Interactive diagram: https://gitdiagram.com/asciinema/asciinema
- Repository: https://github.com/asciinema/asciinema

## Overview

##### Project type and purpose
- This is a Rust-based command-line application (“asciinema CLI”) for recording, playing back, streaming, and uploading terminal sessions in the asciicast format.
- It provides both local functionality (recording to `.cast` files, replay in terminal, serving via a built-in HTTP server) and remote integration (forwarding/relay to an asciinema server).

##### File structure
- Top-level crates and config: `Cargo.toml`, `build.rs`, Dockerfile, Nix flake files → build & deployment.
- `src/main.rs` + `src/cli.rs` → application entrypoint & argument parsing (commands).
- `src/cmd/…` → subcommands (auth, rec, play, stream, upload, convert, cat, session).
- Core modules:
- `src/pty.rs`, `src/io.rs` → spawn and manage pseudo-terminals, capture I/O.
- `src/session.rs`, `src/stream.rs`, `src/server.rs`, `src/forwarder.rs` → session lifecycle, local HTTP server for streaming, and relay to remote.
- `src/encoder/…` and `src/asciicast/…` → produce `.cast` format (v1/v2/v3), raw/txt encoders.
- `src/file_writer.rs` → write cast files.
- `src/api.rs` → REST client for asciinema.org (upload, auth).
- `src/player.rs` → terminal re-player logic.
- `src/notifier.rs`, `src/status.rs` → user notifications, status reporting.
- Tests and examples under `tests/`, documentation in `doc/`.

##### README for additional insights
- Workflow:
- `asciinema rec demo.cast` → record via PTY, write `.cast`.
- `asciinema play demo.cast` → read `.cast`, replay in terminal.
- `asciinema stream --serve` → start local HTTP server, live stream via browser-based player.
- `asciinema stream --relay` / `asciinema upload` → forward to remote server API.
- Architecture is layered: CLI front-end → core session/encoding layer → I/O / networking / storage.

##### Be detailed but focused
- Every major module group, even if it sits in the same binary.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User Terminal"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Main["main.rs"]:::cli
        CLI["cli.rs"]:::cli
        subgraph "Commands"
            direction TB
            Auth["auth"]:::cli
            Cat["cat"]:::cli
            Convert["convert"]:::cli
            PlayCmd["play"]:::cli
            SessionCmd["session"]:::cli
            Upload["upload"]:::cli
        end
    end

    %% Core / Session & Encoding
    subgraph "Core & Encoding" 
        direction TB
        PTY["PTY Manager"]:::core
        IO["I/O Layer"]:::core
        Session["Session Manager"]:::core
        subgraph "Encoder"
            direction TB
            EncMod["encoder/mod"]:::core
            AsciicastEnc["encoder/asciicast"]:::core
            RawEnc["encoder/raw"]:::core
            TxtEnc["encoder/txt"]:::core
            AsciicastV1["asciicast/v1"]:::core
            AsciicastV2["asciicast/v2"]:::core
            AsciicastV3["asciicast/v3"]:::core
            AsciicastUtil["asciicast/util"]:::core
            AsciicastRoot["asciicast.rs"]:::core
        end
        FileWriter["File Writer"]:::core
        Player["Player Module"]:::core
    end

    %% Streaming & Networking
    subgraph "Streaming & Remote"
        direction TB
        subgraph "Streaming Module"
            direction TB
            Server["Local HTTP Server"]:::network
            StreamLogic["Stream Logic"]:::network
        end
        Forwarder["Forwarder"]:::network
        APIClient["API Client"]:::network
        Notifier["Notifier"]:::network
        Status["Status Reporter"]:::network
    end

    %% Storage & External
    LocalStorage[".cast Files"]:::storage
    Browser["Browser Player"]:::external
    RemoteServer["Remote Asciinema Server"]:::external

    %% Connections
    User -->|"stdin/stdout"| Main
    Main --> CLI
    CLI --> Auth
    CLI --> Cat
    CLI --> Convert
    CLI --> PlayCmd
    CLI --> SessionCmd
    CLI --> Upload

    CLI --> PTY
    PTY --> IO
    IO --> Session
    Session --> EncMod
    EncMod --> AsciicastEnc
    EncMod --> RawEnc
    EncMod --> TxtEnc
    AsciicastEnc --> AsciicastV1
    AsciicastEnc --> AsciicastV2
    AsciicastEnc --> AsciicastV3
    AsciicastEnc --> AsciicastUtil
    EncMod --> AsciicastRoot
    EncMod --> FileWriter
    FileWriter --> LocalStorage

    Session --> StreamLogic
    StreamLogic --> Server
    Server --> Browser
    Session --> Forwarder
    Forwarder --> APIClient
    APIClient --> RemoteServer

    Session --> Player
    Player -->|"replay from file"| LocalStorage

    Session --> Notifier
    Forwarder --> Notifier
    Session --> Status
    Forwarder --> Status

    %% Click Events
    click Main "https://github.com/asciinema/asciinema/blob/develop/src/main.rs"
    click CLI "https://github.com/asciinema/asciinema/blob/develop/src/cli.rs"
    click Auth "https://github.com/asciinema/asciinema/blob/develop/src/cmd/auth.rs"
    click Cat "https://github.com/asciinema/asciinema/blob/develop/src/cmd/cat.rs"
    click Convert "https://github.com/asciinema/asciinema/blob/develop/src/cmd/convert.rs"
    click PlayCmd "https://github.com/asciinema/asciinema/blob/develop/src/cmd/play.rs"
    click SessionCmd "https://github.com/asciinema/asciinema/blob/develop/src/cmd/session.rs"
    click Upload "https://github.com/asciinema/asciinema/blob/develop/src/cmd/upload.rs"
    click PTY "https://github.com/asciinema/asciinema/blob/develop/src/pty.rs"
    click IO "https://github.com/asciinema/asciinema/blob/develop/src/io.rs"
    click Session "https://github.com/asciinema/asciinema/blob/develop/src/session.rs"
    click EncMod "https://github.com/asciinema/asciinema/blob/develop/src/encoder/mod.rs"
    click AsciicastEnc "https://github.com/asciinema/asciinema/blob/develop/src/encoder/asciicast.rs"
    click RawEnc "https://github.com/asciinema/asciinema/blob/develop/src/encoder/raw.rs"
    click TxtEnc "https://github.com/asciinema/asciinema/blob/develop/src/encoder/txt.rs"
    click AsciicastV1 "https://github.com/asciinema/asciinema/blob/develop/src/asciicast/v1.rs"
    click AsciicastV2 "https://github.com/asciinema/asciinema/blob/develop/src/asciicast/v2.rs"
    click AsciicastV3 "https://github.com/asciinema/asciinema/blob/develop/src/asciicast/v3.rs"
    click AsciicastUtil "https://github.com/asciinema/asciinema/blob/develop/src/asciicast/util.rs"
    click AsciicastRoot "https://github.com/asciinema/asciinema/blob/develop/src/asciicast.rs"
    click FileWriter "https://github.com/asciinema/asciinema/blob/develop/src/file_writer.rs"
    click Player "https://github.com/asciinema/asciinema/blob/develop/src/player.rs"
    click Server "https://github.com/asciinema/asciinema/blob/develop/src/server.rs"
    click StreamLogic "https://github.com/asciinema/asciinema/blob/develop/src/stream.rs"
    click Forwarder "https://github.com/asciinema/asciinema/blob/develop/src/forwarder.rs"
    click APIClient "https://github.com/asciinema/asciinema/blob/develop/src/api.rs"
    click Notifier "https://github.com/asciinema/asciinema/blob/develop/src/notifier.rs"
    click Status "https://github.com/asciinema/asciinema/blob/develop/src/status.rs"

    %% Styles
    classDef cli fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef core fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef network fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef storage fill:#ffe0b2,stroke:#f4511e,color:#bf360c
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#424242
```
