# bsfishy/boa architecture

> Architecture diagram of the GitHub repository bsfishy/boa, 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/bsfishy/boa
- Repository: https://github.com/bsfishy/boa

## Overview

##### Project's Purpose and Type
- This is a language design project for “boa,” wherein the creator is experimenting with language design ideas, API choices, standard library structure, and language features.
- It isn’t a typical full-stack application or an operational tool yet—it is mostly about design documentation, exploratory code in the src directory, and example programs.

##### File Structure
- Top-level files and configurations: Files like .envrc, .gitignore, build.zig, flake.nix, and zls.json indicate that a build system (using Zig as the main tool) and development environment configurations are set up.
- The src directory contains key modules:
- boac.zig – likely the main driver or compiler shell for the language.
- lexer.zig – responsible for tokenizing the language input.
- parser.zig – constructs parsing logic to create an abstract syntax tree (AST) or similar structure.
- tools.zig – helper utilities or tools that support the design or development of the language.
- The examples directory holds sample “.boa” files (like add.boa, hello_world.boa, postfix.boa, vtable.boa) which illustrate the language's syntax or test its features.
- The presence of documentation files (README.md, notes.md) emphasizes that the repository is used for design notes and experimental ideas.

##### README Content
- The README explains that “boa” is in the design and experimentation phase. Its focus is on sorting out how APIs will function and what language features should be implemented.
- It indicates that when implementation begins, it will likely be housed within this repository.
- The current role is to collect notes, design ideas, and experiment with language features rather than to provide a finished compiler or runtime.

- Component (e.g., Lexer, Parser, Compiler Driver, Tools, Examples, Build Environment) is clearly labeled.
- Dependencies or interactions (for example, the reliance of boac.zig on both lexer.zig and parser.zig).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation/Design
    subgraph "Documentation/Design"
        doc1["README.md"]:::document
        doc2["notes.md"]:::document
    end

    %% Language Core Components
    subgraph "Language Core Components"
        compDriver["Compiler Driver"]:::core
        lexer["Lexer"]:::core
        parser["Parser"]:::core
        tools["Support Tools"]:::core
    end

    %% Example Programs
    subgraph "Example Programs"
        ex["Examples (.boa files)"]:::example
    end

    %% Build and Environment Setup
    subgraph "Build and Environment Setup"
        env1[".envrc"]:::build
        env2[".gitignore"]:::build
        env3["build.zig"]:::build
        env4["build.zig.zon"]:::build
        env5["flake.nix"]:::build
        env6["flake.lock"]:::build
        env7["zls.json"]:::build
    end

    %% Relationships and Flow
    ex -->|"source"| lexer
    lexer -->|"tokens"| parser
    parser -->|"AST"| compDriver
    tools -->|"support"| compDriver
    doc1 -->|"design"| compDriver
    doc2 -->|"design"| compDriver
    compDriver -->|"builds"| env3
    env5 -->|"configures"| env7
    ex -->|"tests"| compDriver

    %% Click Events
    click doc1 "https://github.com/bsfishy/boa/blob/main/README.md"
    click doc2 "https://github.com/bsfishy/boa/blob/main/notes.md"
    click compDriver "https://github.com/bsfishy/boa/blob/main/src/boac.zig"
    click lexer "https://github.com/bsfishy/boa/blob/main/src/lexer.zig"
    click parser "https://github.com/bsfishy/boa/blob/main/src/parser.zig"
    click tools "https://github.com/bsfishy/boa/blob/main/src/tools.zig"
    click ex "https://github.com/bsfishy/boa/tree/main/examples"
    click env1 "https://github.com/bsfishy/boa/blob/main/.envrc"
    click env2 "https://github.com/bsfishy/boa/blob/main/.gitignore"
    click env3 "https://github.com/bsfishy/boa/blob/main/build.zig"
    click env4 "https://github.com/bsfishy/boa/blob/main/build.zig.zon"
    click env5 "https://github.com/bsfishy/boa/blob/main/flake.nix"
    click env6 "https://github.com/bsfishy/boa/blob/main/flake.lock"
    click env7 "https://github.com/bsfishy/boa/blob/main/zls.json"

    %% Styles
    classDef document fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2e86c1,stroke-width:2px;
    classDef example fill:#a9dfbf,stroke:#28b463,stroke-width:2px;
    classDef build fill:#f5cba7,stroke:#e67e22,stroke-width:2px;
```
