# basilisp-lang/basilisp architecture

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

- Interactive diagram: https://gitdiagram.com/basilisp-lang/basilisp
- Repository: https://github.com/basilisp-lang/basilisp

## Overview

##### Project type and purpose
- Basilisp is an open-source Lisp dialect implementation in Python. It provides:
- A compiler/interpreter pipeline for a Clojure-like language (“basilisp”).
- A REPL and CLI interface for interactive use.
- Standard library modules (EDN, JSON, I/O, data structures).
- Extension points via contrib subpackages (bencode, nREPL server, pytest integration, Sphinx support).

##### File structure
- Top-level:
- docs/ – full documentation (Sphinx).
- src/basilisp/ – implementation package.
- tests/ – unit and integration tests.
- CI & packaging: pyproject.toml, GitHub workflows, Makefile, tox.ini.
- src/basilisp splits roughly into:
- cli.py & main.py – entrypoints (console_scripts).
- core.lpy & core/ – core runtime definitions and protocols.
- lang/compiler/ – the compiler pipeline (analyzer, optimizer, generator, nodes).
- lang/… – data structures, reader, runtime, macros, seq, promise, etc.
- io.lpy, json.lpy, edn.lpy, process.lpy, shell.lpy – standard library.
- contrib/ – plugins for testing, docs, nREPL.

##### README
- Confirms it’s a Python-based Lisp targeting Python 3.9+.
- Emphasizes REPL, compiler, standard library, extension focus.
- Mentions test coverage, docs hosted on ReadTheDocs.

- Labels for every component (e.g., “Reader”, “Optimizer”, “nREPL Server Plugin”).
– External systems (gray clouds for file system, network)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and REPL
    subgraph "CLI & REPL"
        CLIEntrypoint["CLI Entrypoint"]:::core
        REPLLoop["REPL Loop"]:::runtime
    end

    %% Compiler Pipeline
    subgraph "Compiler Pipeline"
        Reader["Reader"]:::compiler
        Analyzer["Analyzer"]:::compiler
        Optimizer["Optimizer"]:::compiler
        Generator["Code Generator"]:::compiler
    end

    %% Core Definitions & Protocols
    subgraph "Core Definitions & Protocols"
        CoreDefs["core.lpy"]:::core
        Protocols["protocols.lpy"]:::core
    end

    %% Runtime & Evaluator
    subgraph "Runtime"
        RuntimeEval["Runtime/Evaluator"]:::runtime
    end

    %% Standard Library
    subgraph "Standard Library"
        EDN["EDN"]:::stdlib
        JSON["JSON"]:::stdlib
        IO["I/O"]:::stdlib
        Process["Process"]:::stdlib
        Shell["Shell"]:::stdlib
        PrettyPrint["Pretty‐print"]:::stdlib
        Data["Data Structures"]:::stdlib
    end

    %% Contrib Plugins
    subgraph "Contrib Plugins"
        Bencode["Bencode Plugin"]:::plugin
        nREPL["nREPL Server"]:::plugin
        PytestPlugin["pytest Integration"]:::plugin
        SphinxAuto["Sphinx Autodoc"]:::plugin
    end

    %% External Systems
    subgraph "External Systems"
        FileSystem["File System"]:::external
        Network["Network"]:::external
    end

    %% Testing & CI
    subgraph "Testing & CI"
        Tests["Unit & Integration Tests"]:::ci
        CI["CI/CD Workflows"]:::ci
    end

    %% Connections
    CLIEntrypoint -->|"select mode"| REPLLoop
    CLIEntrypoint -->|"select mode"| Reader
    REPLLoop -->|"input →"| Reader
    Reader -->|"AST"| Analyzer
    Analyzer -->|"optimized AST"| Optimizer
    Optimizer -->|"IR/bytecode"| Generator
    Generator -->|"exec"| RuntimeEval
    RuntimeEval -->|"loads"| CoreDefs
    RuntimeEval -->|"uses"| Protocols
    RuntimeEval -->|"imports"| EDN
    RuntimeEval -->|"imports"| JSON
    RuntimeEval -->|"imports"| IO
    RuntimeEval -->|"imports"| Process
    RuntimeEval -->|"imports"| Shell
    RuntimeEval -->|"imports"| PrettyPrint
    RuntimeEval -->|"imports"| Data
    ContribPlugins(("Contrib Plugins")) -.->|"hooks into"| RuntimeEval
    ContribPlugins -.->|"hooks into"| SphinxAuto
    Tests -->|"invoke"| CLIEntrypoint
    Tests -->|"validate"| RuntimeEval
    CI -->|"runs"| Tests

    FileSystem -->|"read/write"| CLIEntrypoint
    FileSystem -->|"read/write"| RuntimeEval
    Network -->|"nREPL traffic"| nREPL

    %% Click Events
    click CLIEntrypoint "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/cli.py"
    click CLIEntrypoint "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/main.py"
    click REPLLoop "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/repl.lpy"
    click REPLLoop "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/prompt.py"
    click Reader "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/lang/reader.py"
    click Analyzer "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/lang/compiler/analyzer.py"
    click Optimizer "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/lang/compiler/optimizer.py"
    click Generator "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/lang/compiler/generator.py"
    click RuntimeEval "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/lang/runtime.py"
    click CoreDefs "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/core.lpy"
    click Protocols "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/core/protocols.lpy"
    click Bencode "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/contrib/bencode.lpy"
    click nREPL "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/contrib/nrepl_server.lpy"
    click PytestPlugin "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/contrib/pytest/testrunner.py"
    click SphinxAuto "https://github.com/basilisp-lang/basilisp/blob/main/src/basilisp/contrib/sphinx/autodoc.py"

    %% Styles
    classDef compiler fill:#cce5ff,stroke:#004085,color:#004085;
    classDef runtime fill:#d4edda,stroke:#155724,color:#155724;
    classDef stdlib fill:#d4edda,stroke:#155724,color:#155724;
    classDef plugin fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef core fill:#f0f0f0,stroke:#333333,color:#333333;
```
