# filecoin-project/specs architecture

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

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

## Overview

##### Project Type and Purpose
- This is the Filecoin Specification repository: a Hugo-based static documentation site paired with a small dynamic API (Cloudflare Worker).
- Purpose: serve the “single source of truth” spec as a fast, searchable, versioned website and API.

##### File-Structure Analysis
- Top-Level Directories
- content/ – Markdown spec pages (organized by section)
- layouts/ & themes/book/ – Hugo templates & partials for rendering
- api/ – Node.js code (router.js, get.js) bundled via webpack, configured by wrangler.toml for Cloudflare Workers
- config.toml, package.json – Hugo & Node build config
- Patterns
- Static site generator (SSG) for HTML/CSS/JS
- Mono-repo with “frontend” (Hugo) and “backend” (Worker)
- CI/CD via GitHub Actions (/.github/workflows/main.yml) and Fleek (/.fleek.json)

##### README Insights
- Confirms Hugo static-site build with live-reload (`npm start`)
- CI badge → auto-deploy on merge

a. Main Components
1. Developer & GitHub
2. CI/CD Pipeline (GitHub Actions + Fleek)
3. Build System
- Hugo Engine (reads content/, layouts/, assets/)
- Webpack → bundles api/src → Cloudflare Worker script
4. Deployment Targets
- Static Site → Fleek/IPFS (via .fleek.json) + CDN
- API Worker → Cloudflare Workers (via wrangler.toml)
5. End Users’ Browsers
- Static HTML/CSS/JS served from CDN
- JavaScript calls to /api endpoints
b. Relationships and Data Flows
- Dev push → GitHub
- GitHub Actions triggers:
- Hugo builds → emits static assets → deploy to Fleek/IPFS
- Webpack builds API bundle → deploy to Cloudflare Workers
- Browser fetches static content from CDN
- Browser invokes API endpoints for search or dynamic data
c. Architectural Patterns & Principles
- Clear separation: SSG for content vs. micro-service (Worker) for dynamic parts
- Content-as-code: all spec pages in markdown, compiled at build time
- Reuse of Hugo shortcodes and layouts for consistent look & feel
d. Key Technologies
- Hugo (Go-based SSG)
- SCSS/JavaScript assets with Webpack for the API
- Cloudflare Workers (API) via Wrangler
- GitHub Actions for CI
- Fleek/IPFS for static hosting + global CDN

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Repo
    Developer["Developer"]:::blue
    GitHub["GitHub Repo"]:::blue
    Developer -->|push code| GitHub

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        Actions["GitHub Actions"]:::green
    end
    GitHub -->|trigger CI| Actions

    %% Build Steps
    subgraph "Build Steps"
        direction TB
        Hugo["Hugo Build"]:::green
        Webpack["Webpack Build"]:::green

        %% Hugo inputs
        content["Markdown Spec Pages (content/)"]:::code
        layouts["Hugo Templates & Partials (layouts/)"]:::code
        theme["Hugo Theme (themes/book/)"]:::code
        assets["CSS/SCSS & JS Assets (assets/)"]:::code
        staticGen["Generated SVG Diagrams (static/_gen/diagrams/)"]:::code
        toolsDir["Build-Time Tooling (tools/)"]:::green

        %% API inputs
        apiIndex["API Entry Point (api/index.js)"]:::code
        router["Router (api/src/router.js)"]:::code
        getJs["Handler (api/src/get.js)"]:::code
        webpackCfg["Webpack Config (api/src/webpack.config.js)"]:::code
        wranglerCfg["Wrangler Config (api/wrangler.toml)"]:::code
        apiPkg["API Package (api/package.json)"]:::code

        %% Build flows
        Actions --> Hugo
        Actions --> Webpack

        Hugo --> content
        Hugo --> layouts
        Hugo --> theme
        Hugo --> assets
        Hugo --> staticGen
        Hugo --> toolsDir

        Webpack --> apiIndex
        Webpack --> router
        Webpack --> getJs
        Webpack --> webpackCfg
        Webpack --> wranglerCfg
        Webpack --> apiPkg
    end

    %% Deployment
    subgraph "Deploy Targets"
        direction TB
        Fleek["Fleek/IPFS + CDN"]:::orange
        Worker["Cloudflare Workers"]:::orange
    end
    Hugo -->|deploy static| Fleek
    Webpack -->|deploy API| Worker

    %% Runtime
    subgraph "Runtime"
        direction TB
        User["End User Browser"]:::purple
        User -->|fetch static| Fleek
        User -->|call /api| Worker
    end

    %% Click Events for component mapping
    click content "https://github.com/filecoin-project/specs/tree/master/content/"
    click layouts "https://github.com/filecoin-project/specs/tree/master/layouts/"
    click theme "https://github.com/filecoin-project/specs/tree/master/themes/book/"
    click assets "https://github.com/filecoin-project/specs/tree/master/assets/"
    click staticGen "https://github.com/filecoin-project/specs/tree/master/static/_gen/diagrams/"
    click apiIndex "https://github.com/filecoin-project/specs/blob/master/api/index.js"
    click router "https://github.com/filecoin-project/specs/blob/master/api/src/router.js"
    click getJs "https://github.com/filecoin-project/specs/blob/master/api/src/get.js"
    click webpackCfg "https://github.com/filecoin-project/specs/blob/master/api/src/webpack.config.js"
    click wranglerCfg "https://github.com/filecoin-project/specs/blob/master/api/wrangler.toml"
    click apiPkg "https://github.com/filecoin-project/specs/blob/master/api/package.json"
    click toolsDir "https://github.com/filecoin-project/specs/blob/master/tools/diagrams.js"
    click toolsDir "https://github.com/filecoin-project/specs/blob/master/tools/toc.js"
    click toolsDir "https://github.com/filecoin-project/specs/blob/master/tools/readme.js"
    click toolsDir "https://github.com/filecoin-project/specs/blob/master/tools/watch.js"
    click toolsDir "https://github.com/filecoin-project/specs/blob/master/tools/toc/build-model.js"
    click GitHub "https://github.com/filecoin-project/specs/blob/master/.github/workflows/main.yml"
    click Fleek "https://github.com/filecoin-project/specs/blob/master/.fleek.json"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef green fill:#DFF8D8,stroke:#2E8B57,color:#000
    classDef orange fill:#FFE4B5,stroke:#CC8400,color:#000
    classDef purple fill:#E6D8FF,stroke:#800080,color:#000
    classDef code fill:#F0F0F0,stroke:#999,color:#000,stroke-dasharray: 2 2
```
