# filecoin-project/fips architecture

> Architecture diagram of the GitHub repository filecoin-project/fips, 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/fips
- Repository: https://github.com/filecoin-project/fips

## Overview

##### Project Type and Purpose
- This is an open-source governance repository (“Filecoin Improvement Protocol”) that defines the process and houses all Filecoin Improvement Proposals (FIPs), Filecoin Recovery Proposals (FRCs), templates, and related resources.
- There is minimal executable code; most files are Markdown specifications, governance documents, and GitHub Actions workflows for CI.

##### File Structure Analysis
- Top-level directories:
- .github/ – GitHub Actions workflows and templates for PR labeling and testing.
- FIPS/ – All numbered FIP markdown files.
- FRCs/ – All numbered FRC markdown files.
- Community Governance Calls/ – Agendas and notes for community calls.
- resources/ – Supplementary PDF/Go/ipynb reference materials.
- templates/ – Template for new proposal.
- Top-level files: README.md, mission.md, proposing.md, FUNDING.json.
- CI files: .github/workflows/*.yml and supporting Python scripts.

##### README Insights
- Describes the governance process: proposal submission, review, classification (FTP, FOP, FRP).
- Links to external specification repo (specs) where the protocol spec is updated.
- Lists all FIPs/FRCs with status, tying the Markdown content to community and technical steering.

a. Main Components
- Repository Content (Docs Layer): FIPS, FRCs, templates, community call notes, resources.
- CI/CD Layer: GitHub Actions workflows (labeling, tests).
- Contributors (Actors): Community members, authors, reviewers, stewards.
- External Services: GitHub hosting, GitHub Actions runners, external specs repo.
b. Relationships & Interactions
- Contributors submit PRs → CI runs workflows → Labeler & test suites validate → Maintainers review → Merge.
- Merged FIPs trigger downstream updates in the Filecoin Specs repository and community calls.
c. Architectural Patterns
- Content-centric repo with a GitOps style workflow.
- A “documentation pipeline” where PR → CI → review → merge → external sync.
d. Key Technologies
- Markdown for spec files.
- GitHub Actions (.yml, Python labeler).
- GitHub as VCS and issue/PR tracking.
- External spec repository integration via hyperlinks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Authors["Authors"]:::actor
    Reviewers["Reviewers & Stewards"]:::actor

    %% Subgraph: Content Authoring
    subgraph "Content Authoring"
        direction TB
        FIPS["FIPS Directory"]:::content
        FRCs["FRCs Directory"]:::content
        Templates["Proposal Template"]:::content
        Calls["Community Call Notes"]:::content
        Resources["Supplementary Resources"]:::content
        PRTemplate["Pull Request Template"]:::process
        README["README.md"]:::content
        Mission["mission.md"]:::content
        Proposing["proposing.md"]:::content
        Funding["FUNDING.json"]:::content
        Codeowners["CODEOWNERS"]:::content
        Gitignore[".gitignore"]:::content
    end

    %% Subgraph: CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        MainWF["Main Workflow (main.yml)"]:::process
        TestWF["Test Workflow (test.yml)"]:::process
        LabelerScript["GitHub Labeler Script"]:::process
        LabelerTests["Labeler Test Suite"]:::process
        Requirements["Python Dependencies (.txt)"]:::process
    end

    %% Subgraph: Governance Review
    subgraph "Governance Review"
        direction TB
        ReviewPR["Review & Merge PR"]:::process
    end

    %% Subgraph: External Integration
    subgraph "External Integration"
        direction TB
        GitHubHost["GitHub Hosting"]:::external
        ActionsRunner["Actions Runner"]:::external
        SpecsRepo["External Specs Repo"]:::external
    end

    %% Connections
    Authors -->|"submit PR"| FIPS
    Authors --> Templates
    FIPS & FRCs & Templates -->|"include PR Template"| PRTemplate
    PRTemplate -->|"PR created in Repo"| GitHubHost
    GitHubHost -->|"trigger workflows"| ActionsRunner
    ActionsRunner --> MainWF
    ActionsRunner --> TestWF
    MainWF -->|"invoke labeler"| LabelerScript
    TestWF -->|"run tests"| LabelerTests
    LabelerScript --> Requirements
    ActionsRunner -->|"report status"| GitHubHost
    GitHubHost --> Reviewers
    Reviewers -->|"merge PR"| GitHubHost
    GitHubHost -->|"sync on merge"| SpecsRepo
    Reviewers --> Calls
    Calls --> Resources

    %% Click Events
    click FIPS "https://github.com/filecoin-project/fips/tree/master/FIPS/"
    click FRCs "https://github.com/filecoin-project/fips/tree/master/FRCs/"
    click Templates "https://github.com/filecoin-project/fips/blob/master/templates/template.md"
    click Calls "https://github.com/filecoin-project/fips/tree/master/Community Governance Calls/"
    click Resources "https://github.com/filecoin-project/fips/tree/master/resources/"
    click MainWF "https://github.com/filecoin-project/fips/blob/master/.github/workflows/main.yml"
    click TestWF "https://github.com/filecoin-project/fips/blob/master/.github/workflows/test.yml"
    click LabelerScript "https://github.com/filecoin-project/fips/blob/master/.github/workflows/githublabeler.py"
    click LabelerTests "https://github.com/filecoin-project/fips/blob/master/.github/workflows/test_githublabeler.py"
    click Requirements "https://github.com/filecoin-project/fips/blob/master/.github/workflows/requirements.txt"
    click PRTemplate "https://github.com/filecoin-project/fips/blob/master/.github/pull_request_template.md"
    click README "https://github.com/filecoin-project/fips/blob/master/README.md"
    click Mission "https://github.com/filecoin-project/fips/blob/master/mission.md"
    click Proposing "https://github.com/filecoin-project/fips/blob/master/proposing.md"
    click Funding "https://github.com/filecoin-project/fips/blob/master/FUNDING.json"
    click Codeowners "https://github.com/filecoin-project/fips/tree/master/CODEOWNERS"
    click Gitignore "https://github.com/filecoin-project/fips/blob/master/.gitignore"

    %% Styles
    classDef content fill:#D0E8FF,stroke:#009,stroke-width:1px
    classDef process fill:#DFFFE0,stroke:#080,stroke-width:1px
    classDef actor fill:#FFD8A8,stroke:#E67A00,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#666,stroke-width:1px
```
