# 3leaps/sysprims-pty architecture

> Architecture diagram of the GitHub repository 3leaps/sysprims-pty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/3leaps/sysprims-pty
- Repository: https://github.com/3leaps/sysprims-pty

## Overview

sysprims-pty is a cross-platform Rust library for real PTY sessions, opaque-byte I/O, resizing, and owned process containment; its portable_pty-compatible API is a migration path, not the whole product. The principal workflow builds a command, opens a native PTY, performs a single contained spawn, exchanges bytes and resizes, then observes completion or terminates and reaps the owned process tree. Unix and Windows implement containment differently; serial ports provide a separate, non-process-backed TTY capability. Relationships for these paths follow the README and shown source references; unsampled details are not inferred.

Main entry points: [`src/win/conpty.rs`](https://github.com/3leaps/sysprims-pty/blob/main/src/win/conpty.rs) (ConPTY adapter), [`src/lib.rs`](https://github.com/3leaps/sysprims-pty/blob/main/src/lib.rs) (PTY interfaces), [`src/unix.rs`](https://github.com/3leaps/sysprims-pty/blob/main/src/unix.rs) (Unix PTY), [`src/win/psuedocon.rs`](https://github.com/3leaps/sysprims-pty/blob/main/src/win/psuedocon.rs) (Pseudo console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["PTY API"]
  node_command["Command builder<br/>[cmdbuilder.rs]"]
  node_pty_api["PTY interfaces<br/>[lib.rs]"]
  node_serial["Serial TTY<br/>[serial.rs]"]
end

subgraph group_unix["Unix backend"]
  node_unix_pty["Unix PTY<br/>[unix.rs]"]
  node_unix_session["Session acquisition<br/>[unix.rs]"]
end

subgraph group_windows["Windows backend"]
  node_conpty_adapter["ConPTY adapter<br/>[conpty.rs]"]
  node_pseudoconsole["Pseudo console<br/>[psuedocon.rs]"]
  node_thread_attributes["Process attributes<br/>[procthreadattr.rs]"]
  node_windows_child["Windows child<br/>[mod.rs]"]
end

subgraph group_lifecycle["Owned lifecycle"]
  node_guard["Containment guard<br/>[lib.rs]"]
end

node_application(("Application"))
node_sysprims["sysprims primitives"]

node_application -->|"builds command"| node_command
node_application -->|"opens PTY"| node_pty_api
node_pty_api -.->|"selects backend"| node_unix_pty
node_pty_api -.->|"selects backend"| node_conpty_adapter
node_pty_api -.->|"offers serial"| node_serial
node_application -->|"spawns contained"| node_conpty_adapter
node_application -->|"spawns contained"| node_unix_pty
node_conpty_adapter -->|"uses command"| node_command
node_conpty_adapter -->|"spawns child"| node_pseudoconsole
node_pseudoconsole -->|"sets attributes"| node_thread_attributes
node_conpty_adapter -->|"owns child"| node_windows_child
node_unix_pty -->|"acquires session"| node_sysprims
node_unix_pty -->|"returns guard"| node_guard
node_conpty_adapter -->|"returns guard"| node_guard
node_application -->|"observes or terminates"| node_guard
node_application -->|"uses byte I/O"| node_pty_api
node_application -->|"resizes PTY"| node_pty_api

click node_command "https://github.com/3leaps/sysprims-pty/blob/main/src/cmdbuilder.rs"
click node_pty_api "https://github.com/3leaps/sysprims-pty/blob/main/src/lib.rs"
click node_serial "https://github.com/3leaps/sysprims-pty/blob/main/src/serial.rs"
click node_unix_pty "https://github.com/3leaps/sysprims-pty/blob/main/src/unix.rs"
click node_unix_session "https://github.com/3leaps/sysprims-pty/blob/main/src/unix.rs"
click node_conpty_adapter "https://github.com/3leaps/sysprims-pty/blob/main/src/win/conpty.rs"
click node_pseudoconsole "https://github.com/3leaps/sysprims-pty/blob/main/src/win/psuedocon.rs"
click node_thread_attributes "https://github.com/3leaps/sysprims-pty/blob/main/src/win/procthreadattr.rs"
click node_windows_child "https://github.com/3leaps/sysprims-pty/blob/main/src/win/mod.rs"
click node_guard "https://github.com/3leaps/sysprims-pty/blob/main/src/lib.rs"

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_command,node_pty_api,node_serial toneBlue
class node_unix_pty,node_unix_session toneAmber
class node_conpty_adapter,node_pseudoconsole,node_thread_attributes,node_windows_child toneMint
class node_guard toneRose
class node_application,node_sysprims toneIndigo
```

## Components

### PTY API

- [Command builder](https://github.com/3leaps/sysprims-pty/blob/main/src/cmdbuilder.rs): `src/cmdbuilder.rs`
- [PTY interfaces](https://github.com/3leaps/sysprims-pty/blob/main/src/lib.rs): `src/lib.rs`
- [Serial TTY](https://github.com/3leaps/sysprims-pty/blob/main/src/serial.rs): `src/serial.rs`

### Unix backend

- [Unix PTY](https://github.com/3leaps/sysprims-pty/blob/main/src/unix.rs): `src/unix.rs`
- [Session acquisition](https://github.com/3leaps/sysprims-pty/blob/main/src/unix.rs): `src/unix.rs`

### Windows backend

- [ConPTY adapter](https://github.com/3leaps/sysprims-pty/blob/main/src/win/conpty.rs): `src/win/conpty.rs`
- [Pseudo console](https://github.com/3leaps/sysprims-pty/blob/main/src/win/psuedocon.rs): `src/win/psuedocon.rs`
- [Process attributes](https://github.com/3leaps/sysprims-pty/blob/main/src/win/procthreadattr.rs): `src/win/procthreadattr.rs`
- [Windows child](https://github.com/3leaps/sysprims-pty/blob/main/src/win/mod.rs): `src/win/mod.rs`

### Owned lifecycle

- [Containment guard](https://github.com/3leaps/sysprims-pty/blob/main/src/lib.rs): `src/lib.rs`

### Other components

- **Application**
- **sysprims primitives**

## Connections

- Application → Command builder: builds command (evidence: `README.md`)
- Application → PTY interfaces: opens PTY (evidence: `README.md`)
- PTY interfaces → Unix PTY: selects backend (evidence: `src/lib.rs`)
- PTY interfaces → ConPTY adapter: selects backend
- PTY interfaces → Serial TTY: offers serial (evidence: `src/lib.rs`)
- Application → ConPTY adapter: spawns contained (evidence: `README.md`)
- Application → Unix PTY: spawns contained (evidence: `README.md`)
- ConPTY adapter → Command builder: uses command (evidence: `src/win/conpty.rs`)
- ConPTY adapter → Pseudo console: spawns child (evidence: `src/win/conpty.rs`)
- Pseudo console → Process attributes: sets attributes (evidence: `src/win/psuedocon.rs`)
- ConPTY adapter → Windows child: owns child (evidence: `src/win/conpty.rs`)
- Unix PTY → sysprims primitives: acquires session (evidence: `README.md`)
- Unix PTY → Containment guard: returns guard (evidence: `src/unix.rs`)
- ConPTY adapter → Containment guard: returns guard (evidence: `README.md`)
- Application → Containment guard: observes or terminates (evidence: `README.md`)
- Application → PTY interfaces: uses byte I/O (evidence: `README.md`)
- Application → PTY interfaces: resizes PTY (evidence: `README.md`)
