How grandkenzy/ferrum works
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”