# grandkenzy/ferrum architecture

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

- Interactive diagram: https://gitdiagram.com/grandkenzy/ferrum
- Repository: https://github.com/grandkenzy/ferrum

## Overview

##### What this project is (from README + tree)
**Ferrum** is a **programming language implementation** (compiler/toolchain) with the stated goal of compiling **directly to machine code** (no heavy runtime). The repository snapshot you shared looks like an **early-stage front-end + platform definitions**:

- A **Python-based lexer** (`code/lexer/*.py`) that tokenizes Ferrum source text.
- **Architecture/OS “headers”** (`code/headers/AMD64/windows.py`) that likely describe ABI/syscall/register/binary layout details needed later by codegen/emitter.
- **Docs** that mirror headers (`docs/headers/amd64/windows.md`).
- A **test** focused on **Windows AMD64 binaries** (`test/prueba_binarios_windows_amd64.py`).

##### How to read the file structure into architectural components
Directories to “containers/components” explicitly:

##### Core code
- `code/lexer/`
- `__init__.py`: package entrypoint; likely exposes the main tokenize API.
- `_process_*.py`: tokenization sub-passes
- `_process_brackets.py`
- `_process_logic_op.py`
- `_process_operator.py`
- `_process_string.py`
- `_process_word.py`
- `_resolve_indent.py`: indicates Python-like indentation semantics (a significant language feature).

This is a classic **pipeline-of-passes lexer** architecture: each `_process_*` module transforms or refines the token stream / character stream.

##### Platform/target definitions
- `code/headers/AMD64/windows.py`
- Treat as **Target/Platform Specification** (Windows x64 ABI, calling convention, object format, syscall interface, PE layout, etc.—whatever it actually encodes).
- `docs/headers/amd64/windows.md`

##### Tests
- `test/prueba_binarios_windows_amd64.py`
- A consumer of `code/headers/...` and/or future codegen.

Purpose: show what Ferrum interacts with.
Include:
- **Developer** (writes Ferrum source)
- **Ferrum Toolchain** (this repo)
- **Target Platform: Windows AMD64** (OS + CPU architecture)
- **Output Artifact**: “machine code/binary” (even if partially implemented now)
- Optional external tools (only if actually used): assembler/linker/object writer. If not in repo yet, mark as **planned/assumed** not factual.

Purpose: show compiler stages and major subsystems.
Even if not all stages exist, it’s OK to include them but **label clearly**:
- “Implemented now” vs “Planned / future”.

Suggested pipeline containers:
##### Binary Packaging (planned) (e.g., PE for Windows) → outputs Executable

Purpose: represent the actual code in this repo most faithfully.
Model `code/lexer` as a component with internal subcomponents (modules) and their data flows:

- `lexer.__init__` (or “Lexer API”)
- orchestrates the pass sequence
- `_resolve_indent` pass (indent/dedent token generation)
- `_process_string` pass
- `_process_word` pass (identifiers/keywords)
- `_process_operator` pass
- `_process_logic_op` pass
- `_process_brackets` pass

Also show:
- `code/headers/AMD64/windows.py` as a separate component: “Target Spec: Windows AMD64”
- `test/prueba_binarios_windows_amd64.py` consuming the target spec (and later the emitter)

##### Architectural patterns worth highlighting
These are visible from the structure and should be explicit callouts:
- **Compiler pipeline / staged transformations** (even if only lexing exists now).
- **Pass-based lexer design**: multiple focused transformation modules.
- **Target abstraction**: `code/headers/<ARCH>/<OS>.py` implies an extensible matrix:
- ARCH: `AMD64`
- OS: `windows`

##### “Don’t overthink it”: maximize component separation (while staying accurate)
Given your instruction to split into “as many components as possible”, do it in a disciplined way:

- Treat **each lexer pass** (`_process_*.py`, `_resolve_indent.py`) as a distinct component.
- Treat **target headers** as a distinct subsystem with:
- “Target: AMD64”
- “OS: Windows”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= System Context (C4 L1) =========
    Dev["Developer"]:::actor
    Src["Ferrum Source Files\n(.fe/.ferrum/etc)"]:::artifact

    subgraph "Ferrum Toolchain (this repo)"
        Readme["Project Overview\nREADME.md"]:::doc

        subgraph "Core Source Code"
            CodeRoot["code/"]:::folder

            %% ========= Pipeline / Containers (C4 L2) =========
            subgraph "Compiler Pipeline"
                LexerC["Lexer (implemented)"]:::implemented
                Tokens[("Tokens")]:::data

                ParserP["Parser (planned)"]:::planned
                AST[("AST")]:::data

                SemP["Semantic Analysis (planned)"]:::planned
                Typed[("Typed AST / Symbol Table")]:::data

                IRP["IR Builder / Optimizer (planned)"]:::planned
                IR[("IR")]:::data

                CodegenP["Codegen / Emitter (planned)"]:::planned
                Obj[("Object / Machine Code Bytes")]:::data

                PackP["Binary Packaging (planned)\n(PE executable for Windows)"]:::planned
                Exe[("Executable")]:::data
            end

            %% ========= Components (C4 L3) - Lexer internals =========
            subgraph "Lexer Components (code/lexer/*)"
                LexPkg["Lexer Package\ncode/lexer/"]:::folder
                LexAPI["Lexer API / Entrypoint\n__init__.py"]:::implemented

                Indent["_resolve_indent.py\nIndent/Dedent Tokens"]:::implemented
                PStr["_process_string.py\nStrings/Literals"]:::implemented
                PWord["_process_word.py\nWords/Identifiers/Keywords"]:::implemented
                POp["_process_operator.py\nOperators"]:::implemented
                PLogic["_process_logic_op.py\nLogic Operators"]:::implemented
                PBr["_process_brackets.py\nBrackets/Delimiters"]:::implemented
            end

            %% ========= Platform / Target definitions =========
            subgraph "Target / Platform Definitions (code/headers/*)"
                HeadersRoot["code/headers/"]:::folder
                AMD64Dir["AMD64/"]:::folder
                WinAMD64["Windows AMD64 Target Spec\nwindows.py"]:::implemented
            end
        end

        %% ========= Docs =========
        subgraph "Documentation"
            DocsRoot["docs/headers/"]:::folder
            DocsAMD64["amd64/"]:::folder
            WinDocs["Windows AMD64 Header Docs\nwindows.md"]:::doc
        end

        %% ========= Tests =========
        subgraph "QA / Tests"
            TestRoot["test/"]:::folder
            BinTest["Binary/Target Test\nWindows AMD64"]:::test
        end
    end

    Target["Target Platform\nWindows + AMD64 CPU"]:::external

    %% ========= Context connections =========
    Dev -->|"writes"| Src
    Src -->|"input:ferrum_source"| LexerC
    LexerC -->|"outputs"| Tokens

    %% ========= Planned pipeline connections =========
    Tokens -->|"feeds"| ParserP
    ParserP -->|"outputs"| AST
    AST -->|"feeds"| SemP
    SemP -->|"outputs"| Typed
    Typed -->|"feeds"| IRP
    IRP -->|"outputs"| IR
    IR -->|"feeds"| CodegenP
    CodegenP -->|"outputs"| Obj
    Obj -->|"feeds"| PackP
    PackP -->|"outputs"| Exe
    Exe -->|"runs_on"| Target

    %% ========= Target spec dependencies =========
    WinAMD64 -->|"ABI/callingconv/binary_layout_consts"| CodegenP
    WinAMD64 <-->|"kept_consistent_with"| WinDocs

    %% ========= Tests =========
    BinTest -->|"validates"| WinAMD64
    BinTest -.->|"future:validates"| Obj
    BinTest -.->|"future:validates"| Exe

    %% ========= Lexer internal flow (pass-based pipeline) =========
    LexerC -->|"orchestrates"| LexAPI
    LexAPI -->|"pass_order"| Indent
    Indent -->|"refines_stream"| PStr
    PStr -->|"refines_stream"| PWord
    PWord -->|"refines_stream"| POp
    POp -->|"refines_stream"| PLogic
    PLogic -->|"refines_stream"| PBr
    PBr -->|"finalizes"| Tokens

    %% ========= Repo structure relationships =========
    Readme -->|"describes"| CodeRoot
    CodeRoot -->|"contains"| LexPkg
    CodeRoot -->|"contains"| HeadersRoot
    DocsRoot -->|"contains"| WinDocs
    TestRoot -->|"contains"| BinTest
    HeadersRoot -->|"has_target_matrix"| AMD64Dir
    AMD64Dir -->|"defines"| WinAMD64
    DocsRoot -->|"mirrors_targets"| DocsAMD64
    DocsAMD64 -->|"documents"| WinDocs

    %% ========= Click Events (from component_mapping) =========
    click Readme "https://github.com/grandkenzy/ferrum/blob/main/README.md"
    click CodeRoot "https://github.com/grandkenzy/ferrum/tree/main/code/"
    click LexPkg "https://github.com/grandkenzy/ferrum/tree/main/code/lexer/"
    click LexAPI "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/__init__.py"
    click PBr "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/_process_brackets.py"
    click PLogic "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/_process_logic_op.py"
    click POp "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/_process_operator.py"
    click PStr "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/_process_string.py"
    click PWord "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/_process_word.py"
    click Indent "https://github.com/grandkenzy/ferrum/blob/main/code/lexer/_resolve_indent.py"
    click HeadersRoot "https://github.com/grandkenzy/ferrum/tree/main/code/headers/"
    click AMD64Dir "https://github.com/grandkenzy/ferrum/tree/main/code/headers/AMD64/"
    click WinAMD64 "https://github.com/grandkenzy/ferrum/blob/main/code/headers/AMD64/windows.py"
    click DocsRoot "https://github.com/grandkenzy/ferrum/tree/main/docs/headers/"
    click DocsAMD64 "https://github.com/grandkenzy/ferrum/tree/main/docs/headers/amd64/"
    click WinDocs "https://github.com/grandkenzy/ferrum/blob/main/docs/headers/amd64/windows.md"
    click TestRoot "https://github.com/grandkenzy/ferrum/tree/main/test/"
    click BinTest "https://github.com/grandkenzy/ferrum/blob/main/test/prueba_binarios_windows_amd64.py"

    %% ========= Styles (color required) =========
    classDef actor fill:#0b1220,stroke:#93c5fd,stroke-width:2px,color:#e5e7eb
    classDef external fill:#111827,stroke:#22c55e,stroke-width:2px,color:#e5e7eb
    classDef artifact fill:#0f172a,stroke:#a78bfa,stroke-width:2px,color:#e5e7eb
    classDef data fill:#0b1220,stroke:#38bdf8,stroke-width:2px,color:#e5e7eb

    classDef implemented fill:#052e16,stroke:#22c55e,stroke-width:2px,color:#dcfce7
    classDef planned fill:#1f2937,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 6 4,color:#e5e7eb

    classDef folder fill:#0b1220,stroke:#f59e0b,stroke-width:2px,color:#fff7ed
    classDef doc fill:#0b1220,stroke:#60a5fa,stroke-width:2px,color:#dbeafe
    classDef test fill:#0b1220,stroke:#f97316,stroke-width:2px,color:#ffedd5
```
