# ipfs/specs architecture

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

- Interactive diagram: https://gitdiagram.com/ipfs/specs
- Repository: https://github.com/ipfs/specs

## Overview

##### Project type and purpose
- This is an open-source “Specs” repository for the IPFS Protocol (the IPFS Specifications website).
- It hosts the protocols (Bitswap, Routing, IPNS, HTTP Gateways, etc.), proposal process (IPIP), and supporting docs (ARCHITECTURE.md, UNIXFS.md, REPO.md, etc.).
- Its primary function is to transform Markdown spec files + templates into a static website, enforce quality with linters, and publish via CI.

##### File structure
- Top-level content folders:
– /IPIP, /http-gateways, /routing, /ipns, root-level .md files (BITSWAP.md, KEYSTORE.md, etc.)
- Site source (/src):
– src/_includes (common partials: header, footer)
– src/css (stylesheets)
– src/[architecture|exchange|http-gateways|ipips|ipns|routing] (pre-built HTML or .md)
- Templates and config:
– template.html, template.md (layout entrypoints)
– package.json & package-lock.json (Node scripts, dependencies)
– Makefile (convenience commands)
- CI/CD:
– .github/workflows/*.yml (build, linter, stale PRs, generated-PRs)

##### README and ARCHITECTURE.md for insights
- Confirms the role of each sub-spec (HTTP Gateways, Block Exchanges, Key Management, etc.)
- Shows badges, contribution process, links to external spec repos (IPLD, multiformats, libp2p)
- ARCHITECTURE.md describes the overall protocol stack (transport, block exchange, data formats, naming, etc.)

##### Main components
1. Content Layer
– Markdown spec files (root-level .md, IPIP proposals)
– Assets (img/, img/components, img/dex-graphs)
2. Static Site Generator
– Node.js + Eleventy (or similar) invoked via package.json scripts / Makefile
– Templates (template.html, template.md, src/_includes)
– CSS processor (src/css)
3. Build & Validation
– Linter (markdownlint, custom rules)
– CI jobs (GitHub Actions: build, lint, stale bot)
4. Deployment
– GitHub Actions → GitHub Pages or hosted CDN
5. External Integrations
– References to ipld.io specs, multiformats, libp2p specs, community forums
– Issue & PR workflows via GitHub (configured in .github/ISSUE_TEMPLATE, CODEOWNERS)

##### Architectural patterns
- Static Site Generation (SSG) pattern
- Continuous Integration / Continuous Deployment (CI/CD)
- Modular content organization: one folder per subsystem/proposal
- Extensibility via IPIP — new specs drop into /IPIP and src/ipips templates

##### Call out technologies & frameworks
- Node.js, NPM (package.json scripts)
- Eleventy (11ty) or equivalent Markdown-to-HTML engine
- Markdownlint (.markdownlint.json)
- GitHub Actions workflows
- Makefile

##### Final checklist for the engineer
- Break the system into the five main layers/components above
- Inputs (content, templates), processes (build, lint), outputs (site, docs)
- External references and community integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content Layer"
        RootSpecs["Root Markdown Specs"]:::content
        IPIP["IPIP Proposals"]:::content
        HTTPG["HTTP Gateways Specs"]:::content
        IPNSs["IPNS Specs"]:::content
        RoutingSpecs["Routing Specs"]:::content
        Assets["Assets (img/ & src/img/)"]:::content
    end

    subgraph "Static Site Generator"
        Eleventy["Eleventy (Node.js)"]:::processing
        Templates["Templates:\ntemplate.html, template.md, src/_includes"]:::processing
        CSS["CSS:\nsrc/css/index.css, src/css/specs.css"]:::processing
        Config["Config:\npackage.json, Makefile"]:::processing
    end

    subgraph "Built Site"
        Site["Built Site\n(HTML, CSS, Assets)"]:::processing
    end

    subgraph "Build & Validation"
        Linter["Linter\n(.markdownlint.json)"]:::processing
        CI["CI Workflows"]:::infra
    end

    subgraph "Deployment"
        Deploy["GitHub Pages / CDN"]:::infra
    end

    subgraph "External Integrations"
        IPLD["IPLD.io, Multiformats, libp2p"]:::external
        Community["Community\n(Issues & PRs)"]:::external
    end

    %% Data Flows
    RootSpecs --> Eleventy
    IPIP --> Eleventy
    HTTPG --> Eleventy
    IPNSs --> Eleventy
    RoutingSpecs --> Eleventy
    Assets --> Eleventy

    Eleventy --> Site
    Templates --> Site
    CSS --> Site
    Config --> Eleventy

    Site --> Linter
    Linter --> CI
    CI --> Deploy

    CI <--> Community
    Community --> RootSpecs

    IPLD -.-> RootSpecs
    IPLD -.-> Eleventy

    %% Click Events
    click IPIP "https://github.com/ipfs/specs/blob/main/IPIP/*.md"
    click HTTPG "https://github.com/ipfs/specs/blob/main/http-gateways/*.md"
    click IPNSs "https://github.com/ipfs/specs/blob/main/ipns/*.md"
    click RoutingSpecs "https://github.com/ipfs/specs/blob/main/routing/*.md"
    click Assets "https://github.com/ipfs/specs/tree/main/img/"
    click Assets "https://github.com/ipfs/specs/tree/main/src/img/"
    click Templates "https://github.com/ipfs/specs/tree/main/src/_includes/"
    click Eleventy "https://github.com/ipfs/specs/blob/main/package.json"
    click Config "https://github.com/ipfs/specs/tree/main/Makefile"
    click CSS "https://github.com/ipfs/specs/blob/main/src/css/index.css"
    click CSS "https://github.com/ipfs/specs/blob/main/src/css/specs.css"
    click Linter "https://github.com/ipfs/specs/blob/main/.markdownlint.json"
    click CI "https://github.com/ipfs/specs/blob/main/.github/workflows/build.yml"
    click CI "https://github.com/ipfs/specs/blob/main/.github/workflows/linter.yml"
    click CI "https://github.com/ipfs/specs/blob/main/.github/workflows/stale.yml"
    click CI "https://github.com/ipfs/specs/blob/main/.github/workflows/generated-pr.yml"
    click Deploy "https://github.com/ipfs/specs/blob/main/.github/workflows/build.yml"
    click Community "https://github.com/ipfs/specs/tree/main/.github/CODEOWNERS"
    click Community "https://github.com/ipfs/specs/blob/main/.github/ISSUE_TEMPLATE/config.yml"
    click Community "https://github.com/ipfs/specs/blob/main/.github/ISSUE_TEMPLATE/open_an_issue.md"

    %% Styles
    classDef content fill:#cfe2f3,stroke:#0366d6,stroke-width:1px
    classDef processing fill:#d9ead3,stroke:#38761d,stroke-width:1px
    classDef infra fill:#f9cb9c,stroke:#b45f06,stroke-width:1px
    classDef external fill:#d9d2e9,stroke:#674ea7,stroke-width:1px
```
