# dullabs/bhai-lang architecture

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

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

## Overview

##### Project Type and Purpose
- Bhai Lang is a toy programming language written in TypeScript, organized as a monorepo.
- It provides:
- A CLI tool (`packages/cli`) for running `.bhai` source files.
- A Parser (`packages/parser`) that turns source text into an AST.
- An Interpreter (`packages/interpreter`) that walks the AST and executes code.
- A documentation site and in-browser playground (`apps/docs`), built with Next.js.
- Shared configuration packages (`packages/config`, `packages/tsconfig`) and a Turborepo orchestrator (`turbo.json`).

##### File-Structure Analysis and Architectural Insights
- Top-level directories:
- `packages/cli`, `packages/parser`, `packages/interpreter` – core language components.
- `packages/config`, `packages/tsconfig` – shared ESLint/TS presets.
- `apps/docs` – Next.js documentation site and interactive playground.
- Build & CI:
- `turbo.json` drives build/test pipelines across packages.
- GitHub Actions workflow (`.github/workflows/node.js.yml`).
- Architectural patterns:
- Parser: recursive-descent with tokenExecutor, producing AST via `parser/src/components`.
- Interpreter: Visitor pattern traverses AST nodes in `interpreter/src/components/visitor`.
- CLI glues Parser → Interpreter.
- Docs site loads both Parser & Interpreter in browser (playground) and server (rendered docs).

1. Source Code (`.bhai` file)
2. CLI Frontend (Node.js executable in `packages/cli`)
3. Parser Module
- Tokenizer
- Parser logic → AST
4. AST (in-memory data structures)
5. Interpreter Module (Visitor pattern)
- Runtime scope management
- Exception handling
6. Console Output (stdout)
7. Documentation Site / Playground
- Next.js server
- Client-side code editor & runner
- Sentry integration (error logging)
8. Monorepo Orchestrator (Turbo) & Shared Configs
9. External Services
- NPM Registry (package distribution)
- GitHub Actions (CI/CD)
- Sentry (monitoring)

##### Interactions & Data Flow
- User runs `bhailang test.bhai` → CLI component
- CLI reads file → hands raw text to Parser
- Parser → Tokenizer → builds tokens → parsing logic → AST
- AST passed to Interpreter → executes statements → writes to stdout
- For the docs playground:
- Browser editor input → client-side parse & interpret → displays output
- Next.js server may pre-render docs and playground page
- Turbo coordinates build/test across packages before publishing to NPM

##### Architectural Patterns & Principles
- Modularization: each concern (parsing, interpreting, CLI, docs) lives in its own package.
- Visitor pattern in the interpreter simplifies AST node handling.
- Monorepo tooling (Turborepo) for fast incremental builds and tests.
- Shared configuration ensures consistent linting and TypeScript settings.
- Separation of concerns between server-side docs and client-side playground code.

##### Essential Elements
- Clear component labels (e.g., “Tokenizer,” “Parser,” “AST,” “Interpreter”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source to Execution Pipeline
    SourceFile[".bhai Source File"]:::external
    CLI["CLI Frontend\n(packages/cli)"]:::cli
    Tokenizer["Tokenizer\n(packages/parser/src/components/tokenizer)"]:::core
    TokenExecutor["Token Executor\n(packages/parser/src/components/tokenExecutor.ts)"]:::core
    ParserLogic["Parser Logic\n(packages/parser/src/components/parser)"]:::core
    AST["AST\n(nodeTypes)"]:::core
    Interpreter["Interpreter\n(packages/interpreter)"]:::core
    Scope["Runtime Scope\n(packages/interpreter/src/components/scope.ts)"]:::core
    Exceptions["Exceptions\n(packages/interpreter/src/exceptions)"]:::core
    ConsoleOut["Console Output (stdout)"]:::external

    SourceFile -->|"run bhailang"| CLI
    CLI -->|"read file"| SourceFile
    CLI -->|"invoke parser"| Tokenizer
    Tokenizer -->|"tokenize"| TokenExecutor
    TokenExecutor -->|"build tokens"| ParserLogic
    ParserLogic -->|"parse"| AST
    AST -->|"interpret"| Interpreter
    Interpreter -->|"manage scope"| Scope
    Interpreter -->|"handle errors"| Exceptions
    Interpreter -->|"output"| ConsoleOut

    %% Documentation Site / Playground
    subgraph "Docs & Playground (Next.js)" 
        NextServer["Next.js Server"]:::docs
        CodeEditor["Code Editor\n(apps/docs/components/Code/CodeEditor)"]:::docs
        Terminal["Terminal\n(apps/docs/components/Code/Terminal)"]:::docs
        SentryClient["Sentry Client Config"]:::docs
        SentryServer["Sentry Server Config"]:::docs
        SentryProps["Sentry Properties"]:::docs
        IndexPage["Index Page\n(apps/docs/pages/index.tsx)"]:::docs
        AppPage["App Wrapper\n(apps/docs/pages/_app.tsx)"]:::docs
    end

    CodeEditor -->|"input code"| Tokenizer
    Tokenizer -->|"tokenize"| ParserLogic
    ParserLogic -->|"parse"| AST
    AST -->|"interpret"| Interpreter
    Interpreter -->|"output"| Terminal
    NextServer -->|"render pages"| IndexPage
    AppPage -->|"load configs"| SentryClient
    NextServer -->|"load configs"| SentryServer
    NextServer -->|"monitor"| SentryProps
    NextServer -->|"serve playground"| CodeEditor

    %% Monorepo Orchestrator & CI/CD
    Turbo["Turborepo\n(turbo.json)"]:::cicd
    GHAction["GitHub Actions\n(.github/workflows/node.js.yml)"]:::cicd
    NPM["NPM Registry"]:::external

    Turbo -->|"build & test"| packages_all["All Packages"]
    GHAction -->|"CI/CD pipeline"| Turbo
    Turbo -->|"publish"| NPM

    %% External Monitoring
    SentryExt["Sentry Service"]:::external
    DocsLink["Docs Site"]:::external

    NextServer -->|"error logs"| SentryExt
    DocsLink --> NextServer

    %% Click Events
    click CLI "https://github.com/dullabs/bhai-lang/blob/develop/packages/cli/src/index.ts"
    click CLI "https://github.com/dullabs/bhai-lang/blob/develop/packages/cli/package.json"
    click Tokenizer "https://github.com/dullabs/bhai-lang/blob/develop/packages/parser/src/components/tokenizer/index.ts"
    click TokenExecutor "https://github.com/dullabs/bhai-lang/blob/develop/packages/parser/src/components/tokenExecutor.ts"
    click ParserLogic "https://github.com/dullabs/bhai-lang/blob/develop/packages/parser/src/components/parser/index.ts"
    click AST "https://github.com/dullabs/bhai-lang/blob/develop/packages/parser/src/components/parser/types/nodeTypes.ts"
    click Interpreter "https://github.com/dullabs/bhai-lang/blob/develop/packages/interpreter/src/components/interpreter.ts"
    click Scope "https://github.com/dullabs/bhai-lang/blob/develop/packages/interpreter/src/components/scope.ts"
    click Exceptions "https://github.com/dullabs/bhai-lang/blob/develop/packages/interpreter/src/exceptions/invalidStateException.ts"
    click Exceptions "https://github.com/dullabs/bhai-lang/blob/develop/packages/interpreter/src/exceptions/nallaPointerException.ts"
    click Exceptions "https://github.com/dullabs/bhai-lang/blob/develop/packages/interpreter/src/exceptions/runtimeException.ts"
    click SentryClient "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/sentry.client.config.js"
    click SentryServer "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/sentry.server.config.js"
    click SentryProps "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/sentry.properties"
    click IndexPage "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/pages/index.tsx"
    click AppPage "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/pages/_app.tsx"
    click CodeEditor "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/components/Code/CodeEditor/index.tsx"
    click Terminal "https://github.com/dullabs/bhai-lang/blob/develop/apps/docs/components/Code/Terminal/index.tsx"
    click TSCONFIG1 "https://github.com/dullabs/bhai-lang/blob/develop/packages/tsconfig/base.json"
    click TSCONFIG2 "https://github.com/dullabs/bhai-lang/blob/develop/packages/tsconfig/nextjs.json"
    click TSCONFIG3 "https://github.com/dullabs/bhai-lang/blob/develop/packages/tsconfig/react-library.json"
    click ESLINT "https://github.com/dullabs/bhai-lang/blob/develop/packages/config/eslint-preset.js"
    click Turbo "https://github.com/dullabs/bhai-lang/blob/develop/turbo.json"
    click GHAction "https://github.com/dullabs/bhai-lang/blob/develop/.github/workflows/node.js.yml"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0066CC
    classDef cli fill:#DFFFE0,stroke:#339900
    classDef docs fill:#FFF8C6,stroke:#CC9900
    classDef cicd fill:#F0F0F0,stroke:#999999
    classDef external fill:#FFE0E0,stroke:#CC0000
```
