# torproject/torspec architecture

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

- Interactive diagram: https://gitdiagram.com/torproject/torspec
- Repository: https://github.com/torproject/torspec

## Overview

##### Project type and purpose
- This repository is not an executable application but a “specification library” for Tor protocols. It holds text‐based protocol definitions, design proposals, and related documentation that guide implementers on how to build compatible Tor software without reading its source code.

##### File structure
- Top‐level files are grouped by protocol domain:
- General interest (tor‐spec.txt, cert‐spec.txt, dir‐spec.txt, etc.)
- Client operations (address‐spec.txt, path‐spec.txt, socks‐extensions.txt, etc.)
- Onion services (rend‐spec-v2.txt, rend‐spec-v3.txt)
- Censorship resistance (bridgedb‐spec.txt, pt‐spec.txt, gettor‐spec.txt)
- Directory authorities (bandwidth‐file‐spec.txt, srv-spec.txt)
- Controller protocol (control‐spec.txt)
- Miscellaneous and historical (dir-list-spec.txt, attic/)
- The proposals/ directory contains change proposals in numerical order and supporting scripts (reindex.py), plus a CI config (.gitlab-ci.yml) to validate or index them.
- .gitignore and versioning under GitLab imply a continuous integration workflow that checks syntax, links, or indexes.

##### README for additional insights
- It defines the purpose of each spec file and groups them by topic.
- It points to the proposal workflow (001-process.txt) and the role of proposals in evolving the main specs.

a. Main components:
- Spec Modules Group: each category (General, Client, Onion, Censorship, Authorities, Controller, Misc).
- Proposals Engine: the repository of design proposals feeding into spec evolution.
- CI Pipeline: linting, indexing, link‐checking, documentation build jobs.
- Consumers/Implementers: external Tor implementations (client, relay, controller libraries) that consume these specs.
- Version Control System (GitLab): source of truth and workflow enforcer.

b. Relationships and interactions:

c. Architectural patterns and design principles:
- Modular documentation: specs are decoupled by topic.
- Evolution-through-proposals: a formal change‐management workflow.
- Continuous validation: automated CI ensures spec integrity.
- Clear separation: stable specs vs. evolving proposals.

d. Key technologies and frameworks:
- Plain text / Markdown for specs.
- Python script (reindex.py) for indexing proposals.
- GitLab CI for pipeline orchestration.
- Version control (Git) for collaboration and branching.

##### Detailed capture of essential elements
- Proposal‐to‐spec transformation.
- Versioning: tags/branches in GitLab.
- Historical/archived docs (attic/) as deprecated.
- How a change in a proposal triggers CI checks, then merges into a stable spec.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Version Control"
        GitLabRepo["GitLab Repo"]:::config
        GitIgnore[".gitignore"]:::config
        README["README.md"]:::config
        GitLabRepo -->|contains| GitIgnore
        GitLabRepo -->|contains| README
    end

    subgraph "Proposals (Drafts)" 
        ProposalsDir["Proposals Directory"]:::docs
        ReindexScript["reindex.py"]:::config
        ProposalsDir -->|uses| ReindexScript
    end

    subgraph "Specification Modules" 
        subgraph "General Interest" 
            TorSpec["tor-spec.txt"]:::docs
            CertSpec["cert-spec.txt"]:::docs
            DirSpec["dir-spec.txt"]:::docs
            VersionSpec["version-spec.txt"]:::docs
        end
        subgraph "Client Operations"
            AddressSpec["address-spec.txt"]:::docs
            PathSpec["path-spec.txt"]:::docs
            SocksSpec["socks-extensions.txt"]:::docs
            ExtOrportSpec["ext-orport-spec.txt"]:::docs
        end
        subgraph "Onion Services"
            RendV3["rend-spec-v3.txt"]:::docs
            AtticRendV2["rend-spec-v2.txt"]:::docs
        end
        subgraph "Censorship Resistance"
            BridgeSpec["bridgedb-spec.txt"]:::docs
            PtSpec["pt-spec.txt"]:::docs
            GettorSpec["gettor-spec.txt"]:::docs
        end
        subgraph "Directory Authorities"
            BandwidthSpec["bandwidth-file-spec.txt"]:::docs
            SrvSpec["srv-spec.txt"]:::docs
        end
        subgraph "Controller Protocol"
            ControlSpec["control-spec.txt"]:::docs
        end
        subgraph "Miscellaneous & Historical"
            DirListSpec["dir-list-spec.txt"]:::docs
            Attic["attic/"]:::docs
        end
    end

    subgraph "Automation"
        CI["CI Pipeline"]:::automation
        CIGitlab[".gitlab-ci.yml"]:::config
        CI -->|configured by| CIGitlab
    end

    Implementers["Implementer/Client & Relay Codebases"]:::external

    GitLabRepo -->|push triggers| CI
    CI -->|validates| ProposalsDir
    CI -->|validates| SpecificationModules
    ProposalsDir -->|propose→review→merge| SpecificationModules
    SpecificationModules -->|consumed by| Implementers

    click TorSpec "https://github.com/torproject/torspec/blob/main/tor-spec.txt"
    click CertSpec "https://github.com/torproject/torspec/blob/main/cert-spec.txt"
    click DirSpec "https://github.com/torproject/torspec/blob/main/dir-spec.txt"
    click VersionSpec "https://github.com/torproject/torspec/blob/main/version-spec.txt"
    click AddressSpec "https://github.com/torproject/torspec/blob/main/address-spec.txt"
    click PathSpec "https://github.com/torproject/torspec/blob/main/path-spec.txt"
    click SocksSpec "https://github.com/torproject/torspec/blob/main/socks-extensions.txt"
    click ExtOrportSpec "https://github.com/torproject/torspec/blob/main/ext-orport-spec.txt"
    click RendV3 "https://github.com/torproject/torspec/blob/main/rend-spec-v3.txt"
    click AtticRendV2 "https://github.com/torproject/torspec/blob/main/attic/rend-spec-v2.txt"
    click BridgeSpec "https://github.com/torproject/torspec/blob/main/bridgedb-spec.txt"
    click PtSpec "https://github.com/torproject/torspec/blob/main/pt-spec.txt"
    click GettorSpec "https://github.com/torproject/torspec/blob/main/gettor-spec.txt"
    click BandwidthSpec "https://github.com/torproject/torspec/blob/main/bandwidth-file-spec.txt"
    click SrvSpec "https://github.com/torproject/torspec/blob/main/srv-spec.txt"
    click ControlSpec "https://github.com/torproject/torspec/blob/main/control-spec.txt"
    click DirListSpec "https://github.com/torproject/torspec/blob/main/dir-list-spec.txt"
    click Attic "https://github.com/torproject/torspec/tree/main/attic/"
    click ProposalsDir "https://github.com/torproject/torspec/tree/main/proposals/"
    click ReindexScript "https://github.com/torproject/torspec/blob/main/proposals/reindex.py"
    click CIGitlab "https://github.com/torproject/torspec/blob/main/.gitlab-ci.yml"
    click GitIgnore "https://github.com/torproject/torspec/blob/main/.gitignore"
    click README "https://github.com/torproject/torspec/blob/main/README.md"

    classDef docs fill:#D0E6FF,stroke:#0366d6
    classDef automation fill:#DFFFE0,stroke:#28a745
    classDef external fill:#FFE8CC,stroke:#d15704
    classDef config fill:#F0F0F0,stroke:#888888
```
