# lotabout/write-a-c-interpreter architecture

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

- Interactive diagram: https://gitdiagram.com/lotabout/write-a-c-interpreter
- Repository: https://github.com/lotabout/write-a-c-interpreter

## Overview

##### Project Type and Purpose
- This is a compiler/interpreter project (“xc.c”) that interprets C code by compiling it into an internal bytecode and running it on a simple virtual machine.
- It comes with a tutorial implementation (“xc‐tutor.c”) and multilingual documentation that walks through each stage: skeleton, virtual machine, lexer, parsing, variables, functions, statements, expressions.

##### File Structure
- Top-level files:
- xc.c            ← the full interpreter’s source
- xc-tutor.c      ← step-by-step tutorial build of the interpreter
- hello.c         ← sample C program used for testing
- tutorial/       ← Markdown guides in multiple languages
- There are no external dependencies or build scripts beyond a simple gcc invocation.
- The codebase implements a linear pipeline (scanning → parsing → code‐gen → VM) in a single C program.

##### README for Additional Insights
- Confirms a self‐interpreting design (the interpreter can compile and run itself).
- Inspired by the “c4” project, but rewritten for clarity.
- Usage: compile xc.c, then feed it one or more .c inputs to produce and execute bytecode, optionally emitting an s-expression view.

a. Main Components
1. Driver / CLI Module
2. Scanner (Lexer)
3. Parser (Recursive-descent, produces AST)
4. Semantic Analyzer / Symbol Table
5. Code Generator (AST → Bytecode)
6. Virtual Machine (Bytecode Interpreter)
7. Runtime Data Structures (stack, heap, call frames)
8. Input Source Files & Output (console, s-expr dump)
b. Relationships and Interactions
Source File → Driver → Scanner → Parser → Semantic Analyzer → Code Generator → VM → Program Output
- The Driver may loop to re-invoke downstream stages (to recompile xc.c itself).
- The VM invokes runtime data structures (stack, global memory).
c. Architectural Patterns / Design Principles
- Pipeline architecture (each stage hands off to the next).
- Recursive-descent parser for simplicity and clarity.
- Stack-based virtual machine model.
- Single executable amalgamating compiler and runtime.
d. Technologies and Libraries
- C99 (gcc) for implementation.
- No third-party libraries; everything is hand-rolled for didactic clarity.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Points
    subgraph "Entry Points"
        XC["xc.c (Driver)"]:::entry
        Tutor["xc-tutor.c (Tutorial Driver)"]:::entry
    end

    %% Source Input
    Hello["hello.c (Sample C Program)"]:::input
    Readme["README.md (Usage Examples)"]:::input

    %% Compile-Time Pipeline
    subgraph "Compile-Time Stages"
        direction TB
        Scan["Scanner (Lexer)"]:::compile
        Parse["Parser (AST Producer)"]:::compile
        Semantic["Semantic Analyzer / Symbol Table"]:::compile
        CodeGen["Code Generator (AST → Bytecode)"]:::compile
        SExprOption["-s Flag → S-Expr Dump"]:::option
    end

    %% Run-Time Environment
    subgraph "Run-Time Environment"
        direction TB
        VM["Virtual Machine (Bytecode Interpreter)"]:::runtime
        RuntimeDS["Runtime Data Structures (Stack, Heap, Frames)"]:::data
        Output["Program Output (Console)"]:::output
    end

    %% Documentation
    subgraph "Tutorial Documentation"
        DocsEn["tutorial/en/"]:::docs
        DocsEs["tutorial/es/"]:::docs
        DocsKo["tutorial/ko/"]:::docs
        DocsPt["tutorial/pt-br/"]:::docs
    end

    %% Data Flows
    Hello -->|feeds into| XC
    XC -->|invokes| Scan
    Scan -->|tokens| Parse
    Parse -->|AST| Semantic
    Semantic -->|annotated AST| CodeGen
    CodeGen -->|bytecode| VM
    CodeGen -->|s-expr| SExprOption
    VM -->|executes| RuntimeDS
    VM -->|results| Output

    %% Bootstrap Loop
    VM -->|can recompile xc.c| XC

    %% Documentation Links
    XC --> DocsEn
    Tutor --> DocsEn

    %% Click Events
    click XC "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click Tutor "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc-tutor.c"
    click Scan "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click Scan "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/3-Lexer.md"
    click Parse "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click Parse "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/4-Top-down-Parsing.md"
    click Semantic "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click Semantic "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/5-Variables.md"
    click CodeGen "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click CodeGen "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/6-Functions.md"
    click CodeGen "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/7-Statements.md"
    click CodeGen "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/8-Expressions.md"
    click VM "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click VM "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/2-Virtual-Machine.md"
    click RuntimeDS "https://github.com/lotabout/write-a-c-interpreter/blob/master/xc.c"
    click RuntimeDS "https://github.com/lotabout/write-a-c-interpreter/blob/master/tutorial/en/2-Virtual-Machine.md"
    click Hello "https://github.com/lotabout/write-a-c-interpreter/blob/master/hello.c"
    click Readme "https://github.com/lotabout/write-a-c-interpreter/blob/master/README.md"
    click DocsEn "https://github.com/lotabout/write-a-c-interpreter/tree/master/tutorial/en/"
    click DocsEs "https://github.com/lotabout/write-a-c-interpreter/tree/master/tutorial/es/"
    click DocsKo "https://github.com/lotabout/write-a-c-interpreter/tree/master/tutorial/ko/"
    click DocsPt "https://github.com/lotabout/write-a-c-interpreter/tree/master/tutorial/pt-br/"

    %% Styles
    classDef entry fill:#FFD700,stroke:#333,stroke-width:1px
    classDef input fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef compile fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef option fill:#FFDEAD,stroke:#333,stroke-width:1px
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef output fill:#FFE4E1,stroke:#333,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px
```
