# asm80/asm80-node architecture

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

## Overview

##### Project type and purpose
- ASM80.js is a Node.js-based command-line assembler and library for assembling source code targeting various 8-bit CPUs (Z80, 8080, 6502, etc.) into multiple output formats (HEX, SREC, CP/M COM, ZX SNA/TAP, C64 PRG, raw BIN).
- It exposes both a CLI tool (`asm80`) and a programmatic API (`asm.js`, `parser.js`, etc.), plus ancillary tools (`hextools.js`, `lfsnode.js`) and static documentation under `docs/`.

##### File structure
- Root configuration and metadata:
- .editorconfig, .eslintrc.js/.json, .gitignore, package.json/lock
- Core modules:
- asm.js — top-level library entrypoint
- parser.js — lexical analysis & parsing into an AST
- core.json — CPU instruction set definitions & encoding tables
- monolith.js — single-file bundle builder (for browser/IDE usage)
- CLI entrypoint:  `lfsnode.js` likely wraps the CLI or supports live-file system uses
- Utility modules:  `hextools.js` for post-processing HEX files
- Test suite:  `test/` contains dozens of assembly sources and their expected binary/listing outputs
- Documentation:  `docs/` contains static HTML, CSS, JS, fonts and `params.json` for the GitBook-style docs

##### README for additional insights
- The CLI interface is driven by `commander`-style flags (`-o`, `-t`, `-m`, etc.)
- CPU type auto-detection by file extension but can be overridden
- Output types vary by target machine conventions
- Core logic and directive support are documented in an external GitBook

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User invoking CLI
    User(["User"]):::user
    CLI["CLI Interface (asm80 executable)"]:::frontend
    User -->|"invoke"| CLI

    %% Command-Line Parser
    Parser["Command-Line Parser"]:::frontend
    CLI -->|"parse flags"| Parser

    %% Assembler Core Library Container
    subgraph "Assembler Core Library"
        direction TB
        CoreEntry["asm.js (Core Entry Point)"]:::core
        Lex["Lexer & Parser"]:::core
        AST["AST Builder"]:::core
        DirHandler["Directive Handler"]:::core
        BackendMgr["CPU Backend Manager"]:::core
        Emitter["Code Generator / Emitter"]:::core
        JSONDef[(core.json)]:::config
    end

    Parser -->|"calls"| CoreEntry
    CoreEntry --> Lex
    CoreEntry --> AST
    CoreEntry --> DirHandler
    CoreEntry --> BackendMgr
    CoreEntry --> Emitter
    BackendMgr -->|"loads"| JSONDef
    Emitter -->|"writes output"| FS

    %% File System I/O
    subgraph "File System I/O"
        direction TB
        FS[(File System)]:::fs
        Reader["Source Reader (.A80, .Z80, etc.)"]:::fs
        Writer["Output Writers (.hex, .lst, .com, .tap, .prg, .bin)"]:::fs
    end

    FS --> Reader
    FS --> Writer
    CoreEntry --> FS

    %% Utility Modules
    subgraph "Utility Modules"
        direction TB
        Hextools["hextools.js"]:::util
        Monolith["monolith.js"]:::util
        LFSNode["lfsnode.js"]:::util
    end

    CoreEntry -->|"use for post-processing"| Hextools
    CoreEntry -->|"bundle for browser"| Monolith
    CoreEntry -->|"live-fs integration"| LFSNode

    %% Test Suite
    TestSuite["Test Suite & Test Files"]:::tests
    TestRunner["Test Runner"]:::tests
    TestRunner -->|"invoke CLI"| CLI
    TestRunner -->|"validate outputs"| Writer
    TestRunner --> TestSuite

    %% Documentation
    Docs(("Static Documentation Site")):::docs
    Docs -->|"reads assets"| DocsAssets["docs/"]:::docs

    %% Click Events
    click CLI "https://github.com/asm80/asm80-node/blob/master/asm80.js"
    click Parser "https://github.com/asm80/asm80-node/blob/master/asm80.js"
    click CoreEntry "https://github.com/asm80/asm80-node/blob/master/asm.js"
    click Lex "https://github.com/asm80/asm80-node/blob/master/parser.js"
    click JSONDef "https://github.com/asm80/asm80-node/blob/master/core.json"
    click Monolith "https://github.com/asm80/asm80-node/blob/master/monolith.js"
    click Hextools "https://github.com/asm80/asm80-node/blob/master/hextools.js"
    click LFSNode "https://github.com/asm80/asm80-node/blob/master/lfsnode.js"
    click TestSuite "https://github.com/asm80/asm80-node/tree/master/test/"
    click DocsAssets "https://github.com/asm80/asm80-node/tree/master/docs/"

    %% Styles
    classDef frontend fill:#cdeffd,stroke:#006f9b;
    classDef core fill:#d4edda,stroke:#2e7d32;
    classDef util fill:#fff3cd,stroke:#ff8f00;
    classDef fs fill:#e2e3e5,stroke:#6c757d;
    classDef config fill:#f8d7da,stroke:#721c24,shape: cylinder;
    classDef docs fill:#e0bbff,stroke:#6a1b9a,shape: cloud;
    classDef tests fill:#f0f0f0,stroke:#343a40;
    classDef user fill:#ffffff,stroke:#000000;
```
