# fedify-dev/fedify architecture

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

- Interactive diagram: https://gitdiagram.com/fedify-dev/fedify
- Repository: https://github.com/fedify-dev/fedify

## Overview

##### Project Type and Purpose
- This is a library/framework for building federated (fediverse) server applications.
- It provides core protocol implementations (ActivityPub, WebFinger, etc.), middlewares, and integrations with various web frameworks.
- It also comes with a CLI toolchain (under the cli folder) for debugging, testing, and even tooling around app startup.

##### File Structure
- Top-level directories like “cli”, “docs”, “examples”, and “src” indicate separation between the command-line tool, documentation, real-world usage demos, and the core code.
- “codegen”: Utilities for generating TypeScript code, helper classes, and schema definitions.
- “federation”: Contains modules that implement federation protocols such as handling callbacks, inbox routing, key caching, and message queuing.
- “nodeinfo”: Implements the NodeInfo protocol for server metadata.
- “runtime”: Provides runtime utilities (key management, URL handling, etc.) and even a “multibase” library.
- “sig”: Manages HTTP signatures, linked data signatures, and proofs.
- “vocab”: Manages the Activity Vocabulary and defines many activity types (like “Create”, “Follow”, “Announce”, etc.) via YAML and test files.
- “webfinger”: Implements the WebFinger protocol handlers and lookup functions.
- “compat”, “shim”, “testing”, and “x” also offer backward compatibility, environment shimming, test fixtures, and miscellaneous integrations.
- Other directories (“.github”, “.devcontainer”, “docs”, “examples”) provide CI/CD pipelines, development container settings, detailed documentation, and sample usage scenarios (such as integrations with Express, Next.js, Hono, etc.).

- Core Library (src) split into functional modules:
- Federation Module: Handling the federated protocols and routing.
- Signature Module: (src/sig) for HTTP signing and integrity proofs.
- Vocabularies: (src/vocab) which define the ActivityPub vocab and associated activities.
- NodeInfo Module: (src/nodeinfo) for handling server metadata requests.
- Code Generation & Runtime: (src/codegen & src/runtime) for dynamic generation of code and runtime support.
- WebFinger Module: (src/webfinger) for both client and server implementations.
- Compatibility/Utilities: (src/compat, src/shim, src/x)
- CLI Toolchain:
- “cli” directory holds the command-line interfaces and tooling scripts which are used for debugging, version management, and testing the framework.
- External Integrations:
- Testing and Documentation:
- “testing” within “src” and various documentation repositories indicate quality assurance and usage guides.

B. Show Relationships & Data Flow:
- Flow between federation components:
- For example, the server receives an ActivityPub request that flows into the federation router (src/federation/router.ts) which then triggers the correct handling (inbox, keycache, middleware, etc.).
- Demonstrate how the signature (src/sig) and vocabulary (src/vocab) modules feed into the federation process by securing communications and parsing/producing standardized activity objects.
- Interactions where the CLI tool leverages other modules for debugging or testing.

C. Highlight Architectural Patterns & Design Principles:
- Modularity: Each protocol (WebFinger, NodeInfo, ActivityPub) is encapsulated in its own module.
- Separation of Concerns: Clear distinction between runtime utilities, federation logic, and external integrations.
- Extensibility: The folder structure (like “compat”, “shim”, and “x”) shows that the design anticipates evolving standards and integration needs.
- Use of Code Generation: “src/codegen” suggests that the framework uses dynamic or build-time techniques to create type-safe wrappers and schemas.

D. Include Relevant Technologies and Frameworks:
- TypeScript is the primary language.
- Integration with Deno is indicated by standard Deno configuration files (deno.json, etc.) and their CLI commands.
- The presence of examples for Express, Next.js, Fresh, and Hono demonstrates multi-framework integration support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Fedify Core Library"
        subgraph "Core Modules"
            A["Federation Module"]:::core
            B["Signature Module"]:::core
            C["Vocabularies Module"]:::core
            D["NodeInfo Module"]:::core
            E["Code Generation Utilities"]:::core
            F["Runtime Utilities"]:::core
            G["WebFinger Module"]:::core
        end
        subgraph "Compatibility/Utilities"
            H["Compat"]:::core
            I["Shim"]:::core
        end
    end

    J["CLI Toolchain"]:::cli
    K["External Integration Demos"]:::external
    L["Documentation"]:::external

    %% Module Dependencies
    A -->|"calls"| B
    A -->|"calls"| C
    A -->|"calls"| D
    A -->|"calls"| G

    E -->|"supports"| F
    F -->|"leverages"| H
    F -->|"leverages"| I

    J -->|"utilizes"| E
    J -->|"utilizes"| F

    K -->|"integrates"| A
    K -->|"integrates"| G

    L -->|"documents"| A

    %% Click Events
    click A "https://github.com/fedify-dev/fedify/tree/main/src/federation"
    click B "https://github.com/fedify-dev/fedify/tree/main/src/sig"
    click C "https://github.com/fedify-dev/fedify/tree/main/src/vocab"
    click D "https://github.com/fedify-dev/fedify/tree/main/src/nodeinfo"
    click E "https://github.com/fedify-dev/fedify/tree/main/src/codegen"
    click F "https://github.com/fedify-dev/fedify/tree/main/src/runtime"
    click G "https://github.com/fedify-dev/fedify/tree/main/src/webfinger"
    click H "https://github.com/fedify-dev/fedify/tree/main/src/compat"
    click I "https://github.com/fedify-dev/fedify/tree/main/src/shim"
    click J "https://github.com/fedify-dev/fedify/tree/main/cli"
    click K "https://github.com/fedify-dev/fedify/tree/main/examples"
    click L "https://github.com/fedify-dev/fedify/tree/main/docs"

    %% Styling
    classDef core fill:#DDEEFF,stroke:#003366,stroke-width:2px;
    classDef cli fill:#FFE4E1,stroke:#FF6347,stroke-width:2px;
    classDef external fill:#E6FFE6,stroke:#008000,stroke-width:2px;
```
