# jank-lang/jank architecture

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

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

## Overview

##### Main Components
- Compiler & Runtime Core:
– Domain: The “compiler+runtime” directory is the heart of the system. It includes CMake build files, source code (both C++ and jank), header files for language internals (e.g., parsing, analysis, code generation, error reporting, runtime, JIT, and interop).
– Sub-components: Show elements such as a Lexical Analyzer, Parser, AST/IR Generator, Semantic Analyzer (with symbol resolution and type management), Code Generation (LLVM integration) and Runtime system (handling native performance, GC, etc.).
- Frontend/Tooling Integration:
– clojure-cli, lein-jank, and nrepl-server directories provide interfaces/integration with popular Clojure tooling ecosystems. Represent these components as “CLI frontends/integrators” that bridge user source code with the jank compiler.
– Include connections to the REPL and interactive components.
- Standard Library & Data Libraries:
– Include components like “jank.data.bencode” that indicate libraries written in jank (or interfacing via C++) to handle specific data formats (e.g., bencode).
- Test Infrastructure:
– There are extensive test suites distributed in subdirectories under “compiler+runtime/test”, “clojure-cli/test-project”, and similar paths (also in “compiler+runtime/test/bash”, “compiler+runtime/test/cpp”) that should be represented as a separate component validating various facets (e.g., language forms, compiler passes, error handling, integration tests).
- Build & Utility Scripts:
– The “bin” directories and scripts (like “check_everything.clj”, “build.yml” in GitHub workflows, and various build scripts in “compiler+runtime/bin”) show that the project uses automated builds, linting, CI, and formatting tools. They form the ancillary infrastructure for continuous integration and deployment.
- Third-Party Dependencies:
– The “third-party” directories inside “compiler+runtime” indicate integrations with external libraries (e.g., Boost, CLI11, ftux, etc.). These should be noted separately to indicate external dependency management.

##### Relationships and Interactions
- Runtime Interaction: From Code Generation output, show graphs leading into the “Runtime System” that executes the compiled code.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly differentiate the compilation pipeline layers (front-end, analysis/transformation, code generation, runtime) and separate tooling/integration layers.
- Modularity: Notice that each of the language components (compiler, CLI integrations, tests) are decoupled to allow independent development and testing.
- Build Automation & Integration: The usage of CMake for the compiler and the CI workflows (GitHub Actions, Travis) reflect continuous integration principles.

##### Relevant Technologies & Frameworks
- LLVM: Emphasize that code generation culminates in LLVM IR and native binary generation.
- C++: The runtime system and interop components are written in C++ (as seen in “include/cpp” and “src/cpp” paths).
- Clojure: Since jank is a Clojure dialect, indicate its compatibility and similarities with Clojure, especially in how the source language (jank) is processed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compiler & Runtime Core
    subgraph "Compiler & Runtime Core"
        direction TB
        LEXER["Lexer"]:::core
        PARSER["Parser"]:::core
        AST["AST/IR Generator"]:::core
        SEMANTIC["Semantic Analyzer"]:::core
        CODEGEN["Code Generation (LLVM)"]:::core
        RUNTIME["Runtime System"]:::core
    end

    %% Frontend/Tooling Integration
    subgraph "Frontend/Tooling Integration"
        direction TB
        CLI["clojure-cli"]:::frontend
        LEIN["lein-jank"]:::frontend
        NREPL["nrepl-server"]:::frontend
    end

    %% Standard Library & Data Libraries
    subgraph "Standard Library & Data Libraries"
        direction TB
        LIB["jank.data.bencode"]:::library
    end

    %% Test Infrastructure
    subgraph "Test Infrastructure"
        direction TB
        TEST["Test Suites"]:::test
    end

    %% Build & Utility Scripts
    subgraph "Build & Utility Scripts"
        direction TB
        BUILD["Build Scripts & CI"]:::build
    end

    %% Third-Party Dependencies
    subgraph "Third-Party Dependencies"
        direction TB
        THIRD["Third-Party Libraries"]:::third
    end

    %% Data Flow from Frontend to Compiler Core
    CLI -->|"input"| LEXER
    LEIN -->|"input"| LEXER
    NREPL -->|"REPL"| LEXER

    %% Compilation pipeline in Compiler & Runtime Core
    LEXER -->|"tokenizes"| PARSER
    PARSER -->|"parses"| AST
    AST -->|"analyzes"| SEMANTIC
    SEMANTIC -->|"transforms"| CODEGEN
    CODEGEN -->|"generates"| RUNTIME

    %% Interaction between Runtime System and Standard Library
    RUNTIME -->|"loads"| LIB

    %% Build & Utility Scripts integration with Compiler Core and Third-Party Dependencies
    BUILD -->|"build"| LEXER
    BUILD -->|"build"| PARSER
    BUILD -->|"build"| AST
    BUILD -->|"build"| SEMANTIC
    BUILD -->|"build"| CODEGEN
    BUILD -->|"build"| RUNTIME
    BUILD -->|"CI"| THIRD

    %% Test Infrastructure validates Frontend and Compiler Core
    TEST -->|"validates"| CLI
    TEST -->|"validates"| LEIN
    TEST -->|"validates"| NREPL
    TEST -->|"verifies"| RUNTIME

    %% External C++ interop (dashed arrow) from Code Generation to Third-Party Dependencies
    CODEGEN -.->|"C++_interop"| THIRD

    %% Additional build monitoring
    RUNTIME -->|"monitor"| BUILD

    %% Click Events
    click RUNTIME "https://github.com/jank-lang/jank/tree/main/compiler+runtime"
    click LEXER "https://github.com/jank-lang/jank/tree/main/compiler+runtime/include"
    click PARSER "https://github.com/jank-lang/jank/tree/main/compiler+runtime/include"
    click AST "https://github.com/jank-lang/jank/tree/main/compiler+runtime/include"
    click SEMANTIC "https://github.com/jank-lang/jank/tree/main/compiler+runtime/include"
    click CODEGEN "https://github.com/jank-lang/jank/tree/main/compiler+runtime/include"
    click CLI "https://github.com/jank-lang/jank/tree/main/clojure-cli"
    click LEIN "https://github.com/jank-lang/jank/tree/main/lein-jank"
    click NREPL "https://github.com/jank-lang/jank/tree/main/nrepl-server"
    click LIB "https://github.com/jank-lang/jank/blob/main/jank.data.bencode"
    click TEST "https://github.com/jank-lang/jank/tree/main/compiler+runtime/test"
    click BUILD "https://github.com/jank-lang/jank/tree/main/bin"
    click THIRD "https://github.com/jank-lang/jank/tree/main/compiler+runtime/third-party"

    %% Styles
    classDef core fill:#f5f7a1,stroke:#333,stroke-width:2px;
    classDef frontend fill:#a1d8f5,stroke:#333,stroke-width:2px;
    classDef library fill:#c1f5a9,stroke:#333,stroke-width:2px;
    classDef test fill:#f5b3a1,stroke:#333,stroke-width:2px;
    classDef build fill:#d1a1f5,stroke:#333,stroke-width:2px;
    classDef third fill:#a1f5d7,stroke:#333,stroke-width:2px;
```
