# imnmr/marie architecture

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

- Interactive diagram: https://gitdiagram.com/imnmr/marie
- Repository: https://github.com/imnmr/marie

## Overview

#### Purpose and Entry Point

MARIE is a compact, incomplete C99 implementation of the MARIE educational machine architecture and its assembly language. The executable is built directly from the single program entry point:

- `main.c`
- `build.sh`

The expected runtime artifact is a command-line `marie` binary; there is no indication of a web, service, or multi-process architecture.

#### Build and Runtime Boundary

Compilation is intentionally direct and has no package manager, generated source, or external runtime dependency:

- `build.sh`
- `main.c`

A C99 compiler is the only required toolchain component. The documented build uses optimization (`-O2`) and produces a native executable. The repository-level `.editorconfig` and `.gitignore` do not participate in runtime behavior.

#### Machine Emulator Core

The central architectural component is the MARIE machine emulator, implemented in the monolithic source file:

- `main.c`

This layer is expected to own machine state such as memory, registers, instruction decoding, and execution control. Because the repository contains no separate modules, the CPU model and instruction execution loop are colocated with all other program behavior.

#### Assembly-Language Handling

The project implements MARIE assembly language in addition to machine execution:

- `main.c`

Assembly parsing/translation and machine-program loading are therefore part of the same process and source unit as emulation. The key boundary is between source-level assembly input and the internal representation consumed by the MARIE execution engine.

#### Primary Control Flow

The likely top-level flow is a command-line driven pipeline:

1. Native process starts in `main` within `main.c`.
2. Input assembly or machine-program content is accepted and interpreted.
3. Program instructions/data are loaded into MARIE machine state.
4. The emulator repeatedly fetches, decodes, and executes MARIE instructions.
5. Execution terminates on the architecture’s halt/stop condition or an input/runtime error.

All control flow remains in-process; no IPC, persistence service, network API, database, or background worker is present in the repository.

#### Infrastructure and External Boundaries

The only material external boundary is the host operating environment: command-line invocation, filesystem-based source/program input, standard C runtime facilities, and native compilation.

- `main.c`
- `build.sh`

No third-party libraries, cloud infrastructure, containers, CI definitions, or external services are represented. Licensing is AGPL-3.0-only:

- `LICENSE`

Main entry points: [`main.c`](https://github.com/imnmr/marie/blob/main/main.c) (Program entry), [`build.sh`](https://github.com/imnmr/marie/blob/main/build.sh) (Build script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Native Build"]
  node_build_script["Build script<br/>shell build<br/>[build.sh]"]
  node_c_compiler{{"C99 compiler<br/>host toolchain"}}
  node_marie_binary["marie binary<br/>native executable"]
end

subgraph group_runtime["MARIE Runtime"]
  node_cli{{"Command line<br/>host interface"}}
  node_main["Program entry<br/>C entry point<br/>[main.c]"]
  node_program_input["Program input<br/>assembly or machine program"]
  node_assembly_handler["Assembly handling<br/>parser and translator<br/>[main.c]"]
  node_program_loader["Program loader<br/>machine loader<br/>[main.c]"]
  node_machine_state[("MARIE machine state<br/>CPU registers and memory<br/>[main.c]")]
  node_execution_loop["Fetch-decode-execute loop<br/>emulator core<br/>[main.c]"]
  node_host_io{{"Host runtime I/O<br/>C runtime boundary"}}
end

node_build_script -->|"invokes"| node_c_compiler
node_c_compiler -->|"produces"| node_marie_binary
node_cli -->|"launches"| node_marie_binary
node_marie_binary -->|"enters"| node_main
node_cli -->|"supplies"| node_program_input
node_host_io -->|"reads"| node_program_input
node_main -->|"interprets input"| node_assembly_handler
node_program_input -->|"source program"| node_assembly_handler
node_assembly_handler -->|"translated program"| node_program_loader
node_program_loader -->|"initializes"| node_machine_state
node_main -->|"starts execution"| node_execution_loop
node_execution_loop -->|"fetches and updates"| node_machine_state
node_execution_loop -->|"reports I/O or errors"| node_host_io

click node_build_script "https://github.com/imnmr/marie/blob/main/build.sh"
click node_main "https://github.com/imnmr/marie/blob/main/main.c"
click node_assembly_handler "https://github.com/imnmr/marie/blob/main/main.c"
click node_program_loader "https://github.com/imnmr/marie/blob/main/main.c"
click node_machine_state "https://github.com/imnmr/marie/blob/main/main.c"
click node_execution_loop "https://github.com/imnmr/marie/blob/main/main.c"

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_build_script,node_c_compiler,node_marie_binary toneBlue
class node_cli,node_main,node_program_input,node_assembly_handler,node_program_loader,node_machine_state,node_execution_loop,node_host_io toneAmber
```

## Components

### Native Build

- [Build script](https://github.com/imnmr/marie/blob/main/build.sh): shell build · Compiles the program as optimized C99. · `build.sh`
- **C99 compiler**: host toolchain
- **marie binary**: native executable

### MARIE Runtime

- **Command line**: host interface · Invokes the emulator and supplies program input.
- [Program entry](https://github.com/imnmr/marie/blob/main/main.c): C entry point · Starts the in-process assembly and emulation pipeline. · `main.c`
- **Program input**: assembly or machine program · Read from host-provided input or filesystem.
- [Assembly handling](https://github.com/imnmr/marie/blob/main/main.c): parser and translator · Interprets MARIE assembly into a loadable program representation. · `main.c`
- [Program loader](https://github.com/imnmr/marie/blob/main/main.c): machine loader · Places instructions and data into MARIE state. · `main.c`
- [MARIE machine state](https://github.com/imnmr/marie/blob/main/main.c): CPU registers and memory · `main.c`
- [Fetch-decode-execute loop](https://github.com/imnmr/marie/blob/main/main.c): emulator core · Runs instructions until halt or an error. · `main.c`
- **Host runtime I/O**: C runtime boundary · Provides standard runtime and filesystem interaction.

## Connections

- Build script → C99 compiler: invokes
- C99 compiler → marie binary: produces
- Command line → marie binary: launches
- marie binary → Program entry: enters
- Command line → Program input: supplies
- Host runtime I/O → Program input: reads
- Program entry → Assembly handling: interprets input
- Program input → Assembly handling: source program
- Assembly handling → Program loader: translated program
- Program loader → MARIE machine state: initializes
- Program entry → Fetch-decode-execute loop: starts execution
- Fetch-decode-execute loop → MARIE machine state: fetches and updates
- Fetch-decode-execute loop → Host runtime I/O: reports I/O or errors