# fandango-fuzzer/fandango architecture

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

- Interactive diagram: https://gitdiagram.com/fandango-fuzzer/fandango
- Repository: https://github.com/fandango-fuzzer/fandango

## Overview

##### Project Type & Purpose
FANDANGO is an open-source, Python-based language-driven fuzzer and test-input generator. It provides:
– A CLI (and Python API) for users to specify grammars and semantic constraints
– A core “framework” implementing a genetic/evolutionary search over grammar-derived input populations
– An optional Language Server Protocol endpoint for editor integration

##### High-Level Directory & Component Breakdown
- src/fandango/cli → Command-line entry points, progress UI, suggestion store
- src/fandango/framework.py → The “application layer” glue for orchestrating grammar loading, search, constraint checking
- src/fandango/language → Grammar‐processing layer, including ANTLR parser files, convert/parse/grammar AST, symbol & tree modules
- src/fandango/constraints → Constraint‐checking layer (fitness functions, predicate definitions)
- src/fandango/evolution → Evolutionary search layer (population management, mutation, crossover, adaptation, evaluation)
- src/fandango/language/server → LSP server implementation
- utils & demo & docs & evaluation → External resources (conversion scripts, notebook demos, documentation, experimental harnesses)

##### Key Architectural Patterns
– Layered architecture: Presentation (CLI/API/LSP) → Orchestration (framework) → Domain services (grammar, constraints, evolution)
– Pipeline/feedback loop: Grammar → Candidate generation → Constraint evaluation → Selection & evolution → Repeat
– Plugin-style extensibility: Users can drop in new grammars (.fan), constraints (Python code), or even custom mutation/evolution strategies

##### Main Components & Their Interactions
[A] User Interfaces
- CLI: fando commands (src/fandango/cli)
- Python API: import framework.py in user scripts
- LSP Server: language_server.py for editor feedback

[B] Orchestration Layer
- Framework: loads grammar definitions, constraints, instantiates Evolution engine

[C] Core Domain Services
- Grammar Processor (language/*): uses ANTLR-generated parsers (FandangoLexer.g4, FandangoParser.g4) to build ASTs
- Constraint Checker (constraints/*): evaluates semantic constraints on generated inputs
- Evolution Engine (evolution/*): manages population, applies mutation, crossover, adaptation, selects next generation

[D] Outputs & Integrations
- Generated test inputs (console, files)
- Experiment harnesses (evaluation/*)
- Documentation site & Docker/PyPI packaging

##### Putting It All Together
– Start with the user actor on the left (Tester, Editor)
– Show the Presentation layer (CLI/API/LSP) → Orchestration (framework) → Core Domain (grammar, constraints, evolution)
– Branch off from Core Domain to “Generated Inputs” and “Evaluation Harness”
– Finally, link to External Services (PyPI, Docker Hub, CI) to illustrate packaging/deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Tester["Tester / Editor"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI (fando commands)"]:::frontend
        API["Python API"]:::frontend
        LSP["LSP Server"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Framework["Framework (src/fandango/framework.py)"]:::orchestration
    end

    %% Core Domain Services
    subgraph "Core Domain Services"
        subgraph "Grammar Processor"
            Convert["convert.py"]:::core
            GrammarAPI["grammar.py"]:::core
            Parse["parse.py"]:::core
            Symbol["symbol.py"]:::core
            Tree["tree.py"]:::core
            Search["search.py"]:::core
            ParserDir["ANTLR Parsers"]:::core
        end
        subgraph "Constraint Checker"
            Base["base.py"]:::core
            Fitness["fitness.py"]:::core
            Predicates["predicates.py"]:::core
        end
        subgraph "Evolution Engine"
            Adaptation["adaptation.py"]:::core
            Algorithm["algorithm.py"]:::core
            Crossover["crossover.py"]:::core
            EvalEng["evaluation.py"]:::core
            Havoc["havoc.py"]:::core
            Mutation["mutation.py"]:::core
            Population["population.py"]:::core
            Profiler["profiler.py"]:::core
        end
        Logger["Logger"]:::core
    end

    %% Outputs & Integrations
    subgraph "Outputs & Integrations"
        Generated["Generated Test Inputs"]:::external
        EvalHarness["Evaluation Harness"]:::external
        Demo["Demo Inputs / Scripts"]:::external
        Docs["Documentation Site"]:::external
        PyPI["PyPI / Docker"]:::external
        CI["CI/CD (GitHub Actions)"]:::external
    end

    %% Flows
    Tester -->|uses| CLI
    Tester -->|imports| API
    Tester -->|edits via| LSP

    CLI -->|invokes| Framework
    API -->|calls| Framework
    LSP -->|calls| Framework

    Framework -->|load grammar| Convert
    Framework -->|load grammar| GrammarAPI
    Framework -->|load grammar| Parse
    Framework -->|load grammar| Symbol
    Framework -->|load grammar| Tree
    Framework -->|search support| Search
    Framework -->|uses parsers| ParserDir

    Framework -->|check constraints| Base
    Framework -->|evaluate_fitness| Fitness
    Framework -->|apply_predicates| Predicates

    Framework -->|manage_population| Population
    Population -->|next_generation| Adaptation
    Population -->|evaluate| EvalEng
    Population -->|crossover| Crossover
    Population -->|mutate| Mutation
    Population -->|havoc| Havoc
    Population -->|profile| Profiler
    Algorithm -->|controls flow| Population

    %% Genetic Loop
    Convert -->|AST| Search
    Search -->|candidates| Population
    Population -->|individuals| Base
    Base -->|scores| Population

    %% Logging
    Framework -->|log events| Logger
    Search -->|log events| Logger
    Population -->|log events| Logger

    %% Outputs
    Framework -->|emit| Generated
    EvalEng -->|harness| EvalHarness
    Demo -->|examples| Framework
    Docs -->|guides| Tester

    %% Deployment
    Generated --> PyPI
    Generated --> CI
    Docs --> PyPI
    CI --> PyPI
    CI --> DockerHub[Docker Hub]:::external

    %% Click Events
    click CLI "https://github.com/fandango-fuzzer/fandango/tree/main/src/fandango/cli"
    click API "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/framework.py"
    click LSP "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/server/language_server.py"
    click Convert "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/convert.py"
    click GrammarAPI "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/grammar.py"
    click Parse "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/parse.py"
    click Symbol "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/symbol.py"
    click Tree "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/tree.py"
    click Search "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/language/search.py"
    click ParserDir "https://github.com/fandango-fuzzer/fandango/tree/main/src/fandango/language/parser"
    click Base "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/constraints/base.py"
    click Fitness "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/constraints/fitness.py"
    click Predicates "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/constraints/predicates.py"
    click Adaptation "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/adaptation.py"
    click Algorithm "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/algorithm.py"
    click Crossover "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/crossover.py"
    click EvalEng "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/evaluation.py"
    click Havoc "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/havoc.py"
    click Mutation "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/mutation.py"
    click Population "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/population.py"
    click Profiler "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/evolution/profiler.py"
    click Logger "https://github.com/fandango-fuzzer/fandango/blob/main/src/fandango/logger.py"
    click Demo "https://github.com/fandango-fuzzer/fandango/tree/main/demo/"
    click Docs "https://github.com/fandango-fuzzer/fandango/tree/main/docs/"
    click EvalHarness "https://github.com/fandango-fuzzer/fandango/tree/main/evaluation/"
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef orchestration fill:#E6F4EA,stroke:#22863A,stroke-width:1px
    classDef core fill:#FFF5B1,stroke:#D29700,stroke-width:1px
    classDef external fill:#F1F8FF,stroke:#6A737D,stroke-width:1px
```
