# khyeo1011/btw architecture

> Architecture diagram of the GitHub repository khyeo1011/btw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khyeo1011/btw
- Repository: https://github.com/khyeo1011/btw

## Overview

btw is a command-line language tool with check, run, build, assembly, token, parse, and language-server commands. The documented flow reads a source file, lexes and parses it, checks it, then either reports diagnostics, interprets it, or generates assembly for native linking. The README contains no capability details; the workflow and additional compiler stages below are supported by the CLI and driver excerpts. Parser, checker, interpreter, code generator, and LSP implementations were not included in the sampled source, so their paths are limited to the existing src/btw directory.

Main entry points: [`src/btw/driver.py`](https://github.com/khyeo1011/btw/blob/main/src/btw/driver.py) (Compiler driver), [`src/btw/cli.py`](https://github.com/khyeo1011/btw/blob/main/src/btw/cli.py) (Command CLI), [`src/btw/lexer.py`](https://github.com/khyeo1011/btw/blob/main/src/btw/lexer.py) (Lexer), [`src/btw/diagnostics.py`](https://github.com/khyeo1011/btw/blob/main/src/btw/diagnostics.py) (Diagnostic model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and language service"]
  node_cli["Command CLI<br/>[cli.py]"]
  node_lsp["Language server"]
  node_driver["Compiler driver<br/>[driver.py]"]
end

subgraph group_frontend["Compiler frontend"]
  node_lexer["Lexer<br/>[lexer.py]"]
  node_tokens["Tokens and comments<br/>[tokens.py]"]
  node_ast["AST model<br/>[ast.py]"]
  node_parser["Parser"]
end

subgraph group_analysis["Checks and diagnostics"]
  node_checker["Semantic checker"]
  node_bigo["Complexity checks"]
  node_suppress["Diagnostic suppression"]
  node_diagnostics["Diagnostic model<br/>[diagnostics.py]"]
  node_span["Source positions<br/>[span.py]"]
  node_printing["Diagnostic output<br/>[printing.py]"]
end

subgraph group_execution["Execution and output"]
  node_interpreter["Interpreter"]
  node_codegen["Assembly generator"]
end

node_user(("CLI user"))
node_gcc["GCC linker"]
node_stdout(("Program output"))
node_stderr(("Error output"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_driver
node_cli -->|"prints diagnostics"| node_printing
node_cli -->|"starts server"| node_lsp
node_driver -->|"starts service"| node_lsp
node_driver -->|"lexes source"| node_lexer
node_driver -->|"parses tokens"| node_parser
node_driver -->|"checks program"| node_checker
node_driver -->|"checks complexity"| node_bigo
node_driver -->|"applies suppression"| node_suppress
node_driver -->|"runs program"| node_interpreter
node_driver -->|"generates assembly"| node_codegen
node_driver -->|"links assembly"| node_gcc
node_driver -->|"passes output stream"| node_stdout
node_driver -->|"passes error stream"| node_stderr
node_lexer -->|"emits tokens"| node_tokens
node_lexer -->|"emits diagnostics"| node_diagnostics
node_lexer -->|"tracks positions"| node_span
node_ast -->|"uses spans"| node_span
node_ast -->|"types comments"| node_tokens
node_diagnostics -->|"locates issues"| node_span
node_printing -->|"formats issues"| node_diagnostics

click node_cli "https://github.com/khyeo1011/btw/blob/main/src/btw/cli.py"
click node_lsp "https://github.com/khyeo1011/btw/tree/main/src/btw"
click node_driver "https://github.com/khyeo1011/btw/blob/main/src/btw/driver.py"
click node_lexer "https://github.com/khyeo1011/btw/blob/main/src/btw/lexer.py"
click node_tokens "https://github.com/khyeo1011/btw/blob/main/src/btw/tokens.py"
click node_ast "https://github.com/khyeo1011/btw/blob/main/src/btw/ast.py"
click node_parser "https://github.com/khyeo1011/btw/tree/main/src/btw"
click node_checker "https://github.com/khyeo1011/btw/tree/main/src/btw"
click node_bigo "https://github.com/khyeo1011/btw/tree/main/src/btw"
click node_suppress "https://github.com/khyeo1011/btw/tree/main/src/btw"
click node_diagnostics "https://github.com/khyeo1011/btw/blob/main/src/btw/diagnostics.py"
click node_span "https://github.com/khyeo1011/btw/blob/main/src/btw/span.py"
click node_printing "https://github.com/khyeo1011/btw/blob/main/src/btw/printing.py"
click node_interpreter "https://github.com/khyeo1011/btw/tree/main/src/btw"
click node_codegen "https://github.com/khyeo1011/btw/tree/main/src/btw"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lsp,node_driver,node_user toneBlue
class node_lexer,node_tokens,node_ast,node_parser toneAmber
class node_checker,node_bigo,node_suppress,node_diagnostics,node_span,node_printing toneMint
class node_interpreter,node_codegen toneRose
class node_gcc,node_stdout,node_stderr toneIndigo
```

## Components

### CLI and language service

- [Command CLI](https://github.com/khyeo1011/btw/blob/main/src/btw/cli.py): `src/btw/cli.py`
- [Language server](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`
- [Compiler driver](https://github.com/khyeo1011/btw/blob/main/src/btw/driver.py): `src/btw/driver.py`

### Compiler frontend

- [Lexer](https://github.com/khyeo1011/btw/blob/main/src/btw/lexer.py): `src/btw/lexer.py`
- [Tokens and comments](https://github.com/khyeo1011/btw/blob/main/src/btw/tokens.py): `src/btw/tokens.py`
- [AST model](https://github.com/khyeo1011/btw/blob/main/src/btw/ast.py): `src/btw/ast.py`
- [Parser](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`

### Checks and diagnostics

- [Semantic checker](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`
- [Complexity checks](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`
- [Diagnostic suppression](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`
- [Diagnostic model](https://github.com/khyeo1011/btw/blob/main/src/btw/diagnostics.py): `src/btw/diagnostics.py`
- [Source positions](https://github.com/khyeo1011/btw/blob/main/src/btw/span.py): `src/btw/span.py`
- [Diagnostic output](https://github.com/khyeo1011/btw/blob/main/src/btw/printing.py): `src/btw/printing.py`

### Execution and output

- [Interpreter](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`
- [Assembly generator](https://github.com/khyeo1011/btw/tree/main/src/btw): `src/btw`

### Other components

- **CLI user**
- **GCC linker**
- **Program output**
- **Error output**

## Connections

- CLI user → Command CLI: invokes
- Command CLI → Compiler driver: dispatches (evidence: `src/btw/cli.py`)
- Command CLI → Diagnostic output: prints diagnostics (evidence: `src/btw/cli.py`)
- Command CLI → Language server: starts server (evidence: `src/btw/cli.py`)
- Compiler driver → Language server: starts service (evidence: `src/btw/driver.py`)
- Compiler driver → Lexer: lexes source (evidence: `src/btw/driver.py`)
- Compiler driver → Parser: parses tokens (evidence: `src/btw/driver.py`)
- Compiler driver → Semantic checker: checks program (evidence: `src/btw/driver.py`)
- Compiler driver → Complexity checks: checks complexity (evidence: `src/btw/driver.py`)
- Compiler driver → Diagnostic suppression: applies suppression (evidence: `src/btw/driver.py`)
- Compiler driver → Interpreter: runs program (evidence: `src/btw/driver.py`)
- Compiler driver → Assembly generator: generates assembly (evidence: `src/btw/driver.py`)
- Compiler driver → GCC linker: links assembly (evidence: `src/btw/driver.py`)
- Compiler driver → Program output: passes output stream (evidence: `src/btw/driver.py`)
- Compiler driver → Error output: passes error stream (evidence: `src/btw/driver.py`)
- Lexer → Tokens and comments: emits tokens (evidence: `src/btw/lexer.py`)
- Lexer → Diagnostic model: emits diagnostics (evidence: `src/btw/lexer.py`)
- Lexer → Source positions: tracks positions (evidence: `src/btw/lexer.py`)
- AST model → Source positions: uses spans (evidence: `src/btw/ast.py`)
- AST model → Tokens and comments: types comments (evidence: `src/btw/ast.py`)
- Diagnostic model → Source positions: locates issues (evidence: `src/btw/diagnostics.py`)
- Diagnostic output → Diagnostic model: formats issues (evidence: `src/btw/printing.py`)
