# benzakariae03/codexion architecture

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

- Interactive diagram: https://gitdiagram.com/benzakariae03/codexion
- Repository: https://github.com/benzakariae03/codexion

## Overview

1. **Repository shape**
   - This is a single native C executable, `codexion`, built with `make`.
   - The architecture is a thread-based simulation, not a distributed system: one process spawns multiple coder threads plus a monitor thread.

2. **Entry point and startup flow**
   - `main.c` drives the program lifecycle.
   - `validation.c` checks CLI arguments and mode selection (`fifo` or `edf`).
   - `init.c` builds the runtime state from the parsed inputs, then `threads_creation.c` starts the worker threads.

3. **Core domain model**
   - `codexion.h` is the central contract for shared structs, constants, and function prototypes.
   - The main entities are:
     - coder state
     - dongle/resource state
     - global simulation state
     - scheduling/queue state
   - This header is the boundary between the modules that manage parsing, scheduling, threading, and teardown.

4. **Worker subsystem: coder behavior**
   - `coder_routine.c` implements each coder thread’s lifecycle.
   - A coder repeatedly acquires two dongles, performs compile/debug/refactor phases, and decrements its remaining compile count.
   - The routine also checks the shared shutdown flag so a coder can exit cleanly when the simulation ends.

5. **Resource arbitration subsystem**
   - `fifo_scheduler.c`, `edf_scheduler.c`, and `queue.c` handle contention for dongles.
   - Each dongle appears to maintain its own wait structure, so the resource layer is per-dongle rather than one global lock.
   - FIFO serves waiting coders in arrival order; EDF reorders them by urgency, based on how close a coder is to burnout.

6. **Synchronization boundaries**
   - The project relies on `pthread_mutex_t` and `pthread_cond_t` to protect shared state and avoid busy-waiting.
   - `status_mutex`-style protection covers simulation flags and counters.
   - `log.c` uses a dedicated mutex so log lines remain coherent across threads.
   - Individual dongles also have their own synchronization so ownership changes are serialized.

7. **Deadlock avoidance strategy**
   - The simulation prevents circular wait by varying acquisition order: odd coders take one dongle first, even coders take the other first.
   - This keeps the resource graph from forming the classic “everyone holds one, waits for the second” deadlock pattern.

8. **Monitor subsystem**
   - `monitor_routine.c` is the supervisory thread.
   - It periodically checks coder timing state to detect burnout and ignores coders that already finished.
   - On burnout, it flips the global termination flag so the rest of the system can stop.

9. **Timing and waiting**
   - `precise_sleep.c` provides millisecond-level sleeping without excessive CPU use.
   - Waiting is cooperative: coders and the monitor both wake up to re-check shared state rather than spinning.
   - The README indicates `pthread_cond_timedwait` is used so sleepers can also respond to cooldown expiry and shutdown.

10. **Logging and observability**
   - `log.c` centralizes output formatting: `<timestamp_ms> <coder_id> <action>`.
   - The logger is mutex-protected, so concurrent thread output does not interleave.
   - The only message allowed after end-of-simulation conditions is burnout reporting.

11. **Cleanup and shutdown**
   - `clean_up.c` owns teardown of mutexes, condition variables, and allocated runtime objects.
   - The shutdown path is shared: once the monitor or completion logic marks the simulation over, coder threads stop, release resources, and join back before cleanup completes.

12. **Utility and parsing helpers**
   - `ft_atol.c` and `codexion_utils.c` support numeric parsing and small shared helpers.
   - `validation.c` and these utilities form the input boundary, keeping the simulation logic separate from CLI concerns.

13. **How data moves through the system**
   - CLI arguments flow into validation, then into initialization.
   - Initialization creates shared state and per-coder/per-dongle runtime objects.
   - Thread creation hands those objects to the coder and monitor routines.
   - Coders mutate shared resource state under locks; the monitor reads the same state to decide when to stop the simulation.
   - Cleanup consumes the same shared objects after all threads have exited.

14. **Best diagram takeaway**
   - The clearest architecture diagram would show one process with:
     - a main/init/control lane,
     - N coder threads contending for per-dongle resources,
     - one monitor thread watching shared timing state,
     - a shared synchronization/logging layer in the middle,
     - and a cleanup/termination path that is triggered by either completion or burnout.

Main entry points: [`coders/coder_routine.c`](https://github.com/benzakariae03/codexion/blob/main/coders/coder_routine.c) (Coder routine), [`coders/monitor_routine.c`](https://github.com/benzakariae03/codexion/blob/main/coders/monitor_routine.c) (Monitor), [`coders/init.c`](https://github.com/benzakariae03/codexion/blob/main/coders/init.c) (Init runtime), [`coders/clean_up.c`](https://github.com/benzakariae03/codexion/blob/main/coders/clean_up.c) (Cleanup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Startup & control"]
  node_main["main<br/>entrypoint<br/>[main.c]"]
  node_validation["Validate args<br/>cli validation<br/>[validation.c]"]
  node_parse_num["Parse numbers<br/>numeric parsing<br/>[ft_atol.c]"]
  node_utils["Helpers<br/>[codexion_utils.c]"]
  node_init["Init runtime<br/>bootstrap<br/>[init.c]"]
  node_threads["Start threads<br/>thread startup<br/>[threads_creation.c]"]
end

subgraph group_runtime["Worker runtime"]
  node_coder["Coder routine<br/>worker thread<br/>[coder_routine.c]"]
  node_fifo["FIFO scheduler<br/>resource arbitration<br/>[fifo_scheduler.c]"]
  node_edf["EDF scheduler<br/>resource arbitration<br/>[edf_scheduler.c]"]
  node_queue["Wait queue<br/>per-resource queue<br/>[queue.c]"]
  node_monitor["Monitor<br/>supervisor thread<br/>[monitor_routine.c]"]
end

subgraph group_shared["Shared state"]
  node_contract["codexion.h<br/>shared contract<br/>[codexion.h]"]
  node_sim_state[("Sim state<br/>global state")]
  node_resource_state[("Dongles<br/>resource state")]
  node_sync(("Sync layer<br/>mutex/cond"))
  node_log["Logger<br/>thread-safe logging<br/>[log.c]"]
  node_sleep["Timed wait<br/>timing<br/>[precise_sleep.c]"]
end

subgraph group_shutdown["Shutdown & teardown"]
  node_cleanup["Cleanup<br/>teardown<br/>[clean_up.c]"]
end

node_main -->|"parse CLI"| node_validation
node_validation -->|"convert values"| node_parse_num
node_validation -->|"shared checks"| node_utils
node_main -->|"bootstrap"| node_init
node_init -->|"build state"| node_contract
node_init -->|"create"| node_sim_state
node_init -->|"create"| node_resource_state
node_init -->|"launch"| node_threads
node_threads -->|"spawn"| node_coder
node_threads -->|"spawn"| node_monitor
node_coder -->|"request resources"| node_fifo
node_coder -->|"request resources"| node_edf
node_fifo -->|"use"| node_queue
node_edf -->|"use"| node_queue
node_queue -->|"attach"| node_resource_state
node_coder -->|"lock & release"| node_resource_state
node_coder -->|"protect shared state"| node_sync
node_monitor -->|"inspect"| node_sim_state
node_monitor -->|"observe"| node_coder
node_monitor -->|"report"| node_log
node_coder -->|"emit actions"| node_log
node_coder -->|"wait"| node_sleep
node_monitor -->|"poll interval"| node_sleep
node_coder -->|"check shutdown"| node_sim_state
node_monitor -->|"trigger stop"| node_cleanup
node_coder -->|"join after stop"| node_cleanup
node_main -->|"finalize"| node_cleanup
node_cleanup -->|"destroy"| node_contract

click node_main "https://github.com/benzakariae03/codexion/blob/main/coders/main.c"
click node_validation "https://github.com/benzakariae03/codexion/blob/main/coders/validation.c"
click node_parse_num "https://github.com/benzakariae03/codexion/blob/main/coders/ft_atol.c"
click node_utils "https://github.com/benzakariae03/codexion/blob/main/coders/codexion_utils.c"
click node_init "https://github.com/benzakariae03/codexion/blob/main/coders/init.c"
click node_threads "https://github.com/benzakariae03/codexion/blob/main/coders/threads_creation.c"
click node_contract "https://github.com/benzakariae03/codexion/blob/main/coders/codexion.h"
click node_log "https://github.com/benzakariae03/codexion/blob/main/coders/log.c"
click node_sleep "https://github.com/benzakariae03/codexion/blob/main/coders/precise_sleep.c"
click node_coder "https://github.com/benzakariae03/codexion/blob/main/coders/coder_routine.c"
click node_fifo "https://github.com/benzakariae03/codexion/blob/main/coders/fifo_scheduler.c"
click node_edf "https://github.com/benzakariae03/codexion/blob/main/coders/edf_scheduler.c"
click node_queue "https://github.com/benzakariae03/codexion/blob/main/coders/queue.c"
click node_monitor "https://github.com/benzakariae03/codexion/blob/main/coders/monitor_routine.c"
click node_cleanup "https://github.com/benzakariae03/codexion/blob/main/coders/clean_up.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_main,node_validation,node_parse_num,node_utils,node_init,node_threads toneBlue
class node_coder,node_fifo,node_edf,node_queue,node_monitor toneAmber
class node_contract,node_sim_state,node_resource_state,node_sync,node_log,node_sleep toneMint
class node_cleanup toneRose
```

## Components

### Startup & control

CLI entry, validation, initialization, and thread launch.

- [main](https://github.com/benzakariae03/codexion/blob/main/coders/main.c): entrypoint · Program entry and lifecycle driver. · `coders/main.c`
- [Validate args](https://github.com/benzakariae03/codexion/blob/main/coders/validation.c): cli validation · Checks CLI inputs and selects simulation mode. · `coders/validation.c`
- [Parse numbers](https://github.com/benzakariae03/codexion/blob/main/coders/ft_atol.c): numeric parsing · Converts string inputs into numeric configuration values. · `coders/ft_atol.c`
- [Helpers](https://github.com/benzakariae03/codexion/blob/main/coders/codexion_utils.c): shared helpers · Small utility functions used across the executable. · `coders/codexion_utils.c`
- [Init runtime](https://github.com/benzakariae03/codexion/blob/main/coders/init.c): bootstrap · Builds the simulation state from validated inputs. · `coders/init.c`
- [Start threads](https://github.com/benzakariae03/codexion/blob/main/coders/threads_creation.c): thread startup · Creates coder workers and the monitor thread. · `coders/threads_creation.c`

### Worker runtime

Coder threads, monitor thread, and their scheduling/resource flow.

- [Coder routine](https://github.com/benzakariae03/codexion/blob/main/coders/coder_routine.c): worker thread · Acquires two dongles, runs phases, and decrements work remaining. · `coders/coder_routine.c`
- [FIFO scheduler](https://github.com/benzakariae03/codexion/blob/main/coders/fifo_scheduler.c): resource arbitration · Serves waiting coders in arrival order. · `coders/fifo_scheduler.c`
- [EDF scheduler](https://github.com/benzakariae03/codexion/blob/main/coders/edf_scheduler.c): resource arbitration · Prioritizes coders by urgency / burnout proximity. · `coders/edf_scheduler.c`
- [Wait queue](https://github.com/benzakariae03/codexion/blob/main/coders/queue.c): per-resource queue · Per-dongle waiting structure used by the schedulers. · `coders/queue.c`
- [Monitor](https://github.com/benzakariae03/codexion/blob/main/coders/monitor_routine.c): supervisor thread · Watches coder timing state and triggers global stop on burnout. · `coders/monitor_routine.c`

### Shared state

Central contract and synchronization/logging utilities shared by threads.

- [codexion.h](https://github.com/benzakariae03/codexion/blob/main/coders/codexion.h): shared contract · Central header for structs, constants, and prototypes. · `coders/codexion.h`
- **Sim state**: global state · Shared simulation flags, counters, and timing state.
- **Dongles**: resource state · Per-resource ownership and waiting state for contention.
- **Sync layer**: mutex/cond · Mutexes and condition variables protecting shared progress.
- [Logger](https://github.com/benzakariae03/codexion/blob/main/coders/log.c): thread-safe logging · Serialized action output from concurrent threads. · `coders/log.c`
- [Timed wait](https://github.com/benzakariae03/codexion/blob/main/coders/precise_sleep.c): timing · Millisecond sleep and cooperative waiting primitives. · `coders/precise_sleep.c`

### Shutdown & teardown

Termination path and object cleanup.

- [Cleanup](https://github.com/benzakariae03/codexion/blob/main/coders/clean_up.c): teardown · Destroys mutexes, condition variables, and allocated runtime objects. · `coders/clean_up.c`

## Connections

- main → Validate args: parse CLI · Main validates arguments and mode selection before setup.
- Validate args → Parse numbers: convert values · Validation relies on numeric parsing for configuration fields.
- Validate args → Helpers: shared checks · Validation uses helper routines for common input handling.
- main → Init runtime: bootstrap · Initialization runs after successful validation.
- Init runtime → codexion.h: build state · Runtime structures are created according to the shared contract.
- Init runtime → Sim state: create · Initializes global simulation flags and counters.
- Init runtime → Dongles: create · Allocates per-dongle resource state and ownership data.
- Init runtime → Start threads: launch · Hands initialized objects to thread creation.
- Start threads → Coder routine: spawn · Starts one worker thread per coder.
- Start threads → Monitor: spawn · Starts the supervisory monitor thread.
- Coder routine → FIFO scheduler: request resources · Coder threads contend through the FIFO scheduler when enabled.
- Coder routine → EDF scheduler: request resources · Coder threads contend through the EDF scheduler when enabled.
- FIFO scheduler → Wait queue: use · FIFO scheduling is backed by a per-resource wait queue.
- EDF scheduler → Wait queue: use · EDF scheduling reorders the same waiting structure by urgency.
- Wait queue → Dongles: attach · Each dongle maintains its own waiting and ownership state.
- Coder routine → Dongles: lock & release · Worker threads acquire and release dongles under synchronization.
- Coder routine → Sync layer: protect shared state · Workers coordinate through mutexes and condition variables.
- Monitor → Sim state: inspect · Monitor reads timing and completion state to decide when to stop.
- Monitor → Coder routine: observe · Supervises coder progress and burnout timing.
- Monitor → Logger: report · Burnout and state changes are logged in a serialized way.
- Coder routine → Logger: emit actions · Coder actions are written through the thread-safe logger.
- Coder routine → Timed wait: wait · Coders sleep cooperatively between work phases and checks.
- Monitor → Timed wait: poll interval · Monitor wakes periodically rather than spinning.
- Coder routine → Sim state: check shutdown · Workers exit cleanly when the global termination flag is set.
- Monitor → Cleanup: trigger stop · Burnout detection flips the termination path that leads to teardown.
- Coder routine → Cleanup: join after stop · Workers release resources and exit before cleanup completes.
- main → Cleanup: finalize · Main completes shutdown and teardown after threads finish.
- Cleanup → codexion.h: destroy · Teardown walks the same shared objects defined by the contract.
