# fonttools/fontspector architecture

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

- Interactive diagram: https://gitdiagram.com/fonttools/fontspector
- Repository: https://github.com/fonttools/fontspector

## Overview

##### Project Type and Purpose
- Fontspector is a **static analysis tool** for font projects.
- It’s implemented primarily in Rust as a **command-line application**, with OPTIONAL Python integration for running existing fontbakery checks, and a **WASM-based web UI**.
- It’s architected as a set of **library crates**, a CLI front end, plugins (profiles), a Python binding, and a WASM web front end.

##### File Structure
Top-level crates and directories:
- fontbakery-bridge (Python-to-Rust bridge)
- fontspector-checkapi (core check interface + utils)
- fontspector-checkhelper (procedural macros for checks)
- fontspector-cli (actual CLI executable)
- fontspector-py (Python module exposing the Rust runner)
- fontspector-web (WASM web UI + static assets)
- profile-* (built-in and plugin-style profiles that define sets of checks)
- templates (HTML/Markdown templates used for reporting)
- scripts (utilities to build profiles, extract data, port checks)
- Cargo.toml workspace ties everything together.

Key patterns:
- **Modular crates** communicating via a shared API (fontspector-checkapi).
- **Plugin architecture**: external profiles compile to dynamic libraries and are loaded at runtime by the CLI.
- **Multi-language**: Rust core, Python extension, WASM + TypeScript front end.

##### README for Additional Insights
- Single binary bundles built-in checks, profiles, and templates.
- Python support via `--features python` + `--use-python` flag.
- WASM front end built with wasm-pack + npm.
- Plugin profiles built with cargo + `cargo-cp-artifact` and loaded dynamically.

##### Main Components & Relationships
a. Components:
1. **Core API**: fontspector-checkapi + fontspector-checkhelper
2. **CLI Executable**: fontspector-cli
3. **Built-in Profiles**: profile-googlefonts, profile-opentype, profile-universal, etc.
4. **Plugin Profiles**: profile-microsoft, profile-adobe, profile-testplugin, loaded at runtime.
5. **Python Bridge**: fontbakery-bridge + fontspector-py
6. **Web Front End**: fontspector-web (WASM + TS + static assets)
7. **Templates**: HTML/Markdown under templates/
8. **Scripts**: helpers under scripts/
9. **Build & CI**: GitHub Actions workflows, Cargo workspace, wasm-pack, npm.

b. Relationships & Data Flows:
- **fontspector-cli** → depends on → **fontspector-checkapi** & **fontspector-checkhelper**.
- **fontspector-cli** → loads → **built-in profiles** (Rust crates) at compile time.
- **fontspector-cli** → dynamically loads → **plugin profiles** (.fontspectorplugin) at runtime.
- **fontspector-cli** → optionally spawns → **Python interpreter** via fontbakery-bridge when `--use-python` is set.
- **fontspector-cli** → uses → **templates** to render reports (HTML/Markdown).
- **fontspector-py** → wraps → **fontspector-checkapi** to expose to Python/pytest.
- **fontspector-web** → compiles --> WASM that embeds **fontspector-checkapi**, executes in browser, renders via static assets.
- **scripts** → read/write → project files to build profiles or data.

c. Architectural Patterns & Principles:
- **Modular monorepo**: each crate encapsulates a concern.
- **Plugin architecture**: dynamic loading for extensibility.
- **Language bridging**: Python integration via a Rust-based bridge.
- **Dual front ends**: CLI and web (WASM).
- **Template-driven reporting**: separation of logic from presentation.

d. Key Technologies & Frameworks:
- Rust + Cargo workspaces
- Procedural macros (checkhelper)
- Python FFI (maturin, PyO3)
- WASM (wasm-pack) + TypeScript + npm + Webpack
- GitHub Actions (rust.yml, pages.yml)
- Protobuf (for some profile data)
- Jinja/Markdown for reports

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Web Variants
    subgraph "Fontspector System" 
        direction TB

        subgraph "Cargo Workspace"
            direction TB
            CoreAPI["fontspector-checkapi"]:::rust
            Helper["fontspector-checkhelper"]:::rust
            CLI["fontspector-cli"]:::rust
            subgraph "Built-in Profiles"
                direction TB
                GFonts["profile-googlefonts"]:::rust
                OType["profile-opentype"]:::rust
                Universal["profile-universal"]:::rust
                DesignSpace["profile-designspace"]:::rust
                ISO15008["profile-iso15008"]:::rust
            end
            subgraph "Plugin Profiles"
                direction TB
                MSPlugin["profile-microsoft"]:::plugin
                AdobePlugin["profile-adobe"]:::plugin
                TestPlugin["profile-testplugin"]:::plugin
            end
            subgraph "Python Integration"
                direction TB
                Bridge["fontbakery-bridge"]:::python
                PyModule["fontspector-py"]:::python
            end
            subgraph "Web Front End"
                direction TB
                WASM["fontspector-web (WASM + TS)"]:::wasm
            end
            Templates["templates"]:::templates
            Scripts["scripts"]:::scripts
            subgraph "Build & CI"
                direction TB
                CargoWS["Cargo.toml (workspace)"]:::buildci
                RustCI[".github/workflows/rust.yml"]:::buildci
                PagesCI[".github/workflows/pages.yml"]:::buildci
                WebPkg["fontspector-web/www/package.json"]:::buildci
                RootPkg["package.json (root)"]:::buildci
            end
        end

        subgraph "Execution Modes"
            direction TB
            CLIExec["CLI Mode"]:::rust
            WebExec["Web Mode"]:::wasm
            Browser["Browser"]:::wasm
        end
    end

    %% Dependencies and Flows
    CLIExec -->|"depends on"| CoreAPI
    CLIExec -->|"uses"| Helper
    CLIExec -->|"loads compile-time"| GFonts
    CLIExec -->|"loads compile-time"| OType
    CLIExec -->|"loads compile-time"| Universal
    CLIExec -->|"loads compile-time"| DesignSpace
    CLIExec -->|"loads compile-time"| ISO15008
    CLIExec -->|"dynamically loads"| MSPlugin
    CLIExec -->|"dynamically loads"| AdobePlugin
    CLIExec -->|"dynamically loads"| TestPlugin
    CLIExec -->|"renders via"| Templates
    CLIExec -->|"calls scripts"| Scripts
    CLIExec -->|"optionally spawns"| Bridge
    Bridge -->|"calls into"| CoreAPI
    PyModule -->|"wraps"| CoreAPI

    Browser -->|"loads WASM"| WASM
    WebExec -->|"executes in"| Browser
    WASM -->|"embeds and calls"| CoreAPI
    WASM -->|"uses static assets"| Templates

    %% Click Events
    click CoreAPI "https://github.com/fonttools/fontspector/tree/main/fontspector-checkapi/"
    click Helper "https://github.com/fonttools/fontspector/tree/main/fontspector-checkhelper/"
    click CLI "https://github.com/fonttools/fontspector/tree/main/fontspector-cli/"
    click GFonts "https://github.com/fonttools/fontspector/tree/main/profile-googlefonts/"
    click OType "https://github.com/fonttools/fontspector/tree/main/profile-opentype/"
    click Universal "https://github.com/fonttools/fontspector/tree/main/profile-universal/"
    click DesignSpace "https://github.com/fonttools/fontspector/tree/main/profile-designspace/"
    click ISO15008 "https://github.com/fonttools/fontspector/tree/main/profile-iso15008/"
    click MSPlugin "https://github.com/fonttools/fontspector/tree/main/profile-microsoft/"
    click AdobePlugin "https://github.com/fonttools/fontspector/tree/main/profile-adobe/"
    click TestPlugin "https://github.com/fonttools/fontspector/tree/main/profile-testplugin/"
    click Bridge "https://github.com/fonttools/fontspector/tree/main/fontbakery-bridge/"
    click PyModule "https://github.com/fonttools/fontspector/tree/main/fontspector-py/"
    click WASM "https://github.com/fonttools/fontspector/tree/main/fontspector-web/"
    click Templates "https://github.com/fonttools/fontspector/tree/main/templates/"
    click Scripts "https://github.com/fonttools/fontspector/tree/main/scripts/"
    click CargoWS "https://github.com/fonttools/fontspector/blob/main/Cargo.toml"
    click RustCI "https://github.com/fonttools/fontspector/blob/main/.github/workflows/rust.yml"
    click PagesCI "https://github.com/fonttools/fontspector/blob/main/.github/workflows/pages.yml"
    click WebPkg "https://github.com/fonttools/fontspector/blob/main/fontspector-web/www/package.json"
    click RootPkg "https://github.com/fonttools/fontspector/blob/main/package.json"

    %% Styles
    classDef rust fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef python fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef wasm fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef templates fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef plugin fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef scripts fill:#f0f4c3,stroke:#333,stroke-width:1px
    classDef buildci fill:#d7ccc8,stroke:#333,stroke-width:1px
```
