# theunrealtarik/fcpu architecture

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

- Interactive diagram: https://gitdiagram.com/theunrealtarik/fcpu
- Repository: https://github.com/theunrealtarik/fcpu

## Overview

FFC is a Rust-based compiler pipeline for a `.fac` source language. The top-level executable is in `src/main.rs`, while `src/lib` holds the compiler subsystems. The README’s diagram matches the code layout: Source input is parsed into a program model, lowered, assembled, and emitted as final code.

The frontend boundary lives in `src/lib/frontend`. It is split into `lexemes.rs`, `token.rs`, `ast.rs`, and `parser.rs`, which indicates a conventional lexical-analysis → tokenization → AST construction flow. The parser produces the higher-level statement/program representation referenced in the README (`Vec<StatementContext>`).

The backend boundary lives in `src/lib/backend`. It is subdivided into `ir.rs`, `low.rs`, `asm.rs`, and `emit.rs`, which suggests a staged transformation chain from AST/program structures into an intermediate representation, then into a lower-level form, and finally into assembled output. The README explicitly names the middle stages as “Program,” “Lowerer,” and “Assembler.”

Several backend files point to compiler-internal concerns rather than code generation alone: `mem.rs`, `symbol.rs`, and `tags.rs`. These likely manage storage layout, symbol resolution, and metadata/tagging used across lowering and assembly. In architecture terms, these are shared support services consumed by the lowering and emission stages.

`src/lib/error.rs` is the shared error boundary for the whole compiler. Because every stage in a compiler can fail independently, this file likely centralizes diagnostics and propagates errors from lexing through code emission.

`src/lib/mod.rs` and the nested module structure show the public API surface of the library crate. The compiler core is therefore reusable as a library, with the binary wrapper in `main.rs` likely acting as the command-line entry point and orchestration layer.

The README image makes the data flow explicit: source text is converted into parser output, then into a program representation, then lowered and assembled into `Vec<Instruction>` and finally into “Code.” That means the diagram should show a clear one-way pipeline with no visible runtime server or web boundary.

The `test/` directory contains focused `.fac` cases such as `break.fac`, `cast.fac`, `cond.fac`, `loop.fac`, `math.fac`, `scope.fac`, and `unary.fac`. These are feature-oriented compiler tests that exercise control flow, expressions, scoping, and type/operation handling, so they validate frontend parsing and backend lowering semantics rather than application behavior.

The `scripts/signals/` folder is an auxiliary tooling boundary. Its Lua files and `dl_dump.sh` look like support scripts for generating or inspecting raw signal/data files, separate from the Rust compiler proper. They appear to be offline tooling rather than part of the main compilation pipeline.

`Cargo.toml`, `Cargo.lock`, and `Makefile.toml` indicate a standard Rust build setup with additional task automation. For architecture purposes, treat Cargo as the primary build/runtime system and the makefile as convenience tooling around compilation and testing.

Overall, the project is best diagrammed as a compiler with three major layers: frontend parsing, backend lowering/assembly, and shared compiler services (errors, symbols, memory/tags), with tests and scripts sitting beside the main pipeline as validation and tooling.

Main entry points: [`src/lib/mod.rs`](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/mod.rs) (Library), [`src/lib/backend/mod.rs`](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/mod.rs) (Backend), [`src/lib/frontend/mod.rs`](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/mod.rs) (Frontend), [`src/lib/backend/low.rs`](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/low.rs) (Lowering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler"]
  node_main["CLI<br/>binary entrypoint<br/>[main.rs]"]
  node_lib["Library<br/>crate API<br/>[mod.rs]"]
  node_frontend["Frontend<br/>lex/parse stage<br/>[mod.rs]"]
  node_lexemes["Lexemes<br/>scanner<br/>[lexemes.rs]"]
  node_token["Tokens<br/>token model<br/>[token.rs]"]
  node_ast["AST<br/>syntax tree<br/>[ast.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_error(("Errors<br/>diagnostics<br/>[error.rs]"))
  node_backend["Backend<br/>lower/emit stage<br/>[mod.rs]"]
  node_ir["IR<br/>intermediate repr<br/>[ir.rs]"]
  node_low["Lowering<br/>lowerer<br/>[low.rs]"]
  node_asm["Assembler<br/>[asm.rs]"]
  node_emit["Emitter<br/>[emit.rs]"]
  node_memory{{"Layout<br/>compiler support<br/>[mem.rs]"}}
  node_game["Game<br/>domain module<br/>[mod.rs]"]
end

subgraph group_tooling["Tooling"]
  node_signals["Signals<br/>lua tooling<br/>[main.lua]"]
end

subgraph group_validation["Validation"]
  node_tests["FAC tests<br/>compiler cases<br/>[break.fac]"]
end

node_main -->|"uses"| node_lib
node_lib -->|"exposes"| node_frontend
node_lib -->|"exposes"| node_backend
node_lib -->|"shares"| node_error
node_lib -->|"includes"| node_game
node_frontend -->|"scans"| node_lexemes
node_lexemes -->|"forms"| node_token
node_token -->|"builds"| node_ast
node_ast -->|"parsed by"| node_parser
node_parser -->|"hands off"| node_backend
node_backend -->|"represents"| node_ir
node_ir -->|"lowers"| node_low
node_low -->|"assembles"| node_asm
node_asm -->|"emits"| node_emit
node_memory -->|"supports"| node_low
node_memory -->|"supports"| node_asm
node_tests -.->|"validates"| node_frontend
node_tests -.->|"validates"| node_backend
node_signals -.->|"supports"| node_backend

click node_main "https://github.com/theunrealtarik/fcpu/blob/master/src/main.rs"
click node_lib "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/mod.rs"
click node_frontend "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/mod.rs"
click node_lexemes "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/lexemes.rs"
click node_token "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/token.rs"
click node_ast "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/ast.rs"
click node_parser "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/parser.rs"
click node_error "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/error.rs"
click node_backend "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/mod.rs"
click node_ir "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/ir.rs"
click node_low "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/low.rs"
click node_asm "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/asm.rs"
click node_emit "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/emit.rs"
click node_memory "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/mem.rs"
click node_game "https://github.com/theunrealtarik/fcpu/blob/master/src/lib/game/mod.rs"
click node_signals "https://github.com/theunrealtarik/fcpu/blob/master/scripts/signals/main.lua"
click node_tests "https://github.com/theunrealtarik/fcpu/blob/master/test/break.fac"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_lib,node_frontend,node_lexemes,node_token,node_ast,node_parser,node_error,node_backend,node_ir,node_low,node_asm,node_emit,node_memory,node_game toneBlue
class node_signals toneAmber
class node_tests toneMint
```

## Components

### Compiler

Rust compiler crate and its pipeline

- [CLI](https://github.com/theunrealtarik/fcpu/blob/master/src/main.rs): binary entrypoint · Command-line wrapper that orchestrates compilation · `src/main.rs`
- [Library](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/mod.rs): crate API · Public compiler library surface · `src/lib/mod.rs`
- [Frontend](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/mod.rs): lex/parse stage · Source text to structured program representation · `src/lib/frontend/mod.rs`
- [Lexemes](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/lexemes.rs): scanner · Breaks source into lexical units · `src/lib/frontend/lexemes.rs`
- [Tokens](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/token.rs): token model · Token definitions and token stream structure · `src/lib/frontend/token.rs`
- [AST](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/ast.rs): syntax tree · Parsed statement and program structures · `src/lib/frontend/ast.rs`
- [Parser](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/frontend/parser.rs): parser · Builds the higher-level program context from tokens · `src/lib/frontend/parser.rs`
- [Errors](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/error.rs): diagnostics · Shared compiler error boundary · `src/lib/error.rs`
- [Backend](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/mod.rs): lower/emit stage · Transforms program structures into final code · `src/lib/backend/mod.rs`
- [IR](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/ir.rs): intermediate repr · Intermediate program representation · `src/lib/backend/ir.rs`
- [Lowering](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/low.rs): lowerer · Converts program IR into lower-level form · `src/lib/backend/low.rs`
- [Assembler](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/asm.rs): assembler · Shapes lowered data into instructions · `src/lib/backend/asm.rs`
- [Emitter](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/emit.rs): code emitter · Produces final output code · `src/lib/backend/emit.rs`
- [Layout](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/backend/mem.rs): compiler support · Shared storage and layout support used by backend stages · `src/lib/backend/mem.rs`
- [Game](https://github.com/theunrealtarik/fcpu/blob/master/src/lib/game/mod.rs): domain module · Additional library subsystem outside the core pipeline · `src/lib/game/mod.rs`

### Tooling

Auxiliary scripts and build automation

- [Signals](https://github.com/theunrealtarik/fcpu/blob/master/scripts/signals/main.lua): lua tooling · Offline scripts for dumping or inspecting signal data · `scripts/signals/main.lua`

### Validation

Feature-oriented compiler tests

- [FAC tests](https://github.com/theunrealtarik/fcpu/blob/master/test/break.fac): compiler cases · Feature-focused .fac inputs for parser and codegen behavior · `test/break.fac`

## Connections

- CLI → Library: uses · Binary drives the library compiler pipeline
- Library → Frontend: exposes · Public crate surface includes frontend stages
- Library → Backend: exposes · Public crate surface includes backend stages
- Library → Errors: shares · Errors are propagated across the compiler
- Library → Game: includes · Additional library module beside the compiler pipeline
- Frontend → Lexemes: scans · Frontend begins by splitting source into lexemes
- Lexemes → Tokens: forms · Lexemes are converted into tokens
- Tokens → AST: builds · Tokens feed AST and statement structures
- AST → Parser: parsed by · Parser constructs the higher-level program context
- Parser → Backend: hands off · Parsed program flows into backend processing
- Backend → IR: represents · Backend starts from program IR
- IR → Lowering: lowers · IR is lowered into a more concrete form
- Lowering → Assembler: assembles · Lowered form is assembled into instructions
- Assembler → Emitter: emits · Assembler output is turned into final code
- Layout → Lowering: supports · Storage/layout support informs lowering
- Layout → Assembler: supports · Backend assembly uses shared layout metadata
- FAC tests → Frontend: validates · Test cases exercise parsing and syntax handling
- FAC tests → Backend: validates · Test cases exercise lowering and code generation
- Signals → Backend: supports · Auxiliary scripts operate beside compiler output
