# siraben/zkeme80 architecture

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

- Interactive diagram: https://gitdiagram.com/siraben/zkeme80
- Repository: https://github.com/siraben/zkeme80

## Overview

Key Components to Include:

##### Core System Architecture
- Create three main layers in a vertical stack:
a. Hardware Layer (TI-84+ Calculator)
b. Low-Level System Layer (Z80 Assembly)
c. Forth Environment Layer

##### Build System Components
- Build pipeline with these components:
a. Scheme-based Assembler (assembler.scm)
b. OS Source Files
c. Build Process (Makefile/Nix)
d. Output ROM

##### Main System Components
- Assembler System
- Pattern Matching Engine
- Two-Pass Assembly Process

- Operating System Core
- Boot System (boot.scm, boot.fs)
- Hardware Interface Layer
- (display.scm)
- Keyboard (keyboard.scm)
- Flash Memory (flash.scm)
- Interrupts (interrupt.scm)
- Forth Environment
- Core Forth Words (forth.scm)
- Extended Words (words/*.fs)
- Text Processing (text.scm)

- Build-time flow:
- Scheme source → Assembler → Binary ROM
- Runtime flow:
- Hardware interrupts → OS handlers
- Keyboard input → Forth interpreter
- Forth commands → Display output

##### Important Relationships to Highlight
- Two-pass assembly process
- Bootstrap sequence (flash1-5)
- Forth word hierarchy
- Hardware abstraction layers

##### Additional Elements
- Version/build information
- Dependencies (Guile Scheme)
- Extension points for custom Forth words

Special Considerations:
##### Test components and their interaction

Level of Detail:
- Keep hardware details at a high level
- Interaction between assembly and Forth layers
- Detail the build process components
- Clear separation between core OS and user-extensible parts

Remember to include notes about:
- The ANS Forth standard compliance
- Extension mechanisms
- Test suite integration
- Build system requirements (Guile/Nix)

This will provide a comprehensive view of both the build-time and runtime architecture while maintaining clarity about the system's unique features and design choices.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Build
        Assembler["Assembler (Scheme)"]
        BuildSystem["Build System"]
        OSSource["OS Source Files"]
        ROM[("Output ROM")]
    end

    subgraph "Hardware Layer"
        TI84["TI-84+ Calculator"]
        Flash["Flash Memory"]
        Display["Display"]
        Keyboard["Keyboard"]
        Interrupts["Interrupts"]
    end

    subgraph "Low-Level System"
        BootSystem["Boot System"]
        HWInterface["Hardware Interface Layer"]
        CoreUtils["Core Utilities"]
    end

    subgraph "Forth Environment"
        ForthCore["Core Forth"]
        TextProc["Text Processing"]
        ExtWords["Extended Words"]
        TestSuite["Test Suite"]
    end

    %% Build System Relationships
    Assembler --> ROM
    BuildSystem --> ROM
    OSSource --> Assembler

    %% Hardware Interface Relationships
    HWInterface --> Flash
    HWInterface --> Display
    HWInterface --> Keyboard
    HWInterface --> Interrupts

    %% Boot and Core Relationships
    BootSystem --> HWInterface
    CoreUtils --> HWInterface
    
    %% Forth Environment Relationships
    ForthCore --> HWInterface
    TextProc --> ForthCore
    ExtWords --> ForthCore
    TestSuite --> ForthCore

    %% Runtime Flow
    Keyboard --> HWInterface
    Display --> HWInterface
    ROM --> BootSystem

    %% Styling
    classDef hardware fill:#D4D4D4,stroke:#333
    classDef system fill:#9EC5FE,stroke:#333
    classDef forth fill:#FFB366,stroke:#333
    classDef build fill:#90EE90,stroke:#333

    class TI84,Flash,Display,Keyboard,Interrupts hardware
    class BootSystem,HWInterface,CoreUtils system
    class ForthCore,TextProc,ExtWords,TestSuite forth
    class Assembler,BuildSystem,OSSource,ROM build

    %% Click Events
    click Assembler "https://github.com/siraben/zkeme80/blob/master/src/assembler.scm"
    click BuildSystem "https://github.com/siraben/zkeme80/tree/master/Makefile"
    click BootSystem "https://github.com/siraben/zkeme80/blob/master/src/boot.scm"
    click Display "https://github.com/siraben/zkeme80/blob/master/src/display.scm"
    click Keyboard "https://github.com/siraben/zkeme80/blob/master/src/keyboard.scm"
    click Flash "https://github.com/siraben/zkeme80/blob/master/src/flash.scm"
    click Interrupts "https://github.com/siraben/zkeme80/blob/master/src/interrupt.scm"
    click ForthCore "https://github.com/siraben/zkeme80/blob/master/src/forth.scm"
    click TextProc "https://github.com/siraben/zkeme80/blob/master/src/text.scm"
    click ExtWords "https://github.com/siraben/zkeme80/tree/master/words"
    click TestSuite "https://github.com/siraben/zkeme80/blob/master/words/test-suite.fs"
    click CoreUtils "https://github.com/siraben/zkeme80/blob/master/src/util.scm"
```
