# shfahimdev/formulanegativeone architecture

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

- Interactive diagram: https://gitdiagram.com/shfahimdev/formulanegativeone
- Repository: https://github.com/shfahimdev/formulanegativeone

## Overview

1. **Project shape**
   - This is a small native C simulation program, built as a single executable rather than a framework-based app.
   - The architecture is deliberately split into a few low-level modules: input capture, vehicle state, physics, rendering, and the main loop.

2. **Top-level control flow**
   - `main.c` is the orchestrator.
   - It runs a fixed-rate loop at roughly 60 Hz, pulls the latest input state, translates that into forces, advances the physics, and then hands the updated state to rendering.

3. **Input subsystem**
   - `keyhold.c/h` is a background-thread input reader using Linux’s `/dev/input` event system.
   - It tracks key-down duration with microsecond precision, which is important because the simulator cares about continuous hold time rather than discrete key presses.

4. **Simulation state boundary**
   - `object.c/h` defines the rigid-body state of the car: position, velocity, acceleration, mass, and friction parameters.
   - This module is the shared data model passed between input interpretation, physics integration, and rendering.

5. **Physics subsystem**
   - `physics.c/h` contains the core motion model: force application, Euler integration, and kinetic friction.
   - The simulation currently treats the car as a body moving on a 2D X/Z plane, so physics is simplified to translational motion with no heading/orientation yet.

6. **Control-to-force mapping**
   - The keyboard controls are not directly “move object” commands; they become forces applied to the rigid body.
   - W/S drive forward and braking/reverse forces, while A/D apply lateral forces in the current model.

7. **Rendering boundary**
   - `render.c/h` is isolated as the presentation layer.
   - Even if the visual system is minimal today, the file split shows the intended boundary: rendering should consume simulation state, not contain simulation logic.

8. **System-level dependencies**
   - The build uses plain `gcc` with `-lm` and `-lpthread`, so the runtime depends on the math library and POSIX threads.
   - Access to the keyboard device requires elevated privileges (`sudo`) because it reads from `/dev/input`.

9. **Current architectural constraints**
   - The simulator is intentionally “bare metal”: no engine, no ECS, no networking, no persistence, and no asset pipeline.
   - The main technical constraints are the hardcoded input device path, fixed timestep integration, and the absence of car orientation and tire dynamics.

10. **Likely architecture diagram framing**
   - A good diagram would show one central simulation loop in `main.c`, with arrows from the Linux input device into `keyhold`, then into `main`, then into `physics`, updating `object` state, and finally into `render`.
   - The key boundary is that input is asynchronous, while physics/rendering are driven synchronously by the loop.

Main entry points: [`main.c`](https://github.com/shfahimdev/formulanegativeone/blob/main/main.c) (Main loop), [`object.c`](https://github.com/shfahimdev/formulanegativeone/blob/main/object.c) (Car state), [`keyhold.c`](https://github.com/shfahimdev/formulanegativeone/blob/main/keyhold.c) (Keyhold), [`physics.c`](https://github.com/shfahimdev/formulanegativeone/blob/main/physics.c) (Physics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control loop"]
  node_main(("Main loop<br/>orchestrator<br/>[main.c]"))
  node_keyhold["Keyhold<br/>input reader<br/>[keyhold.c]"]
  node_inputdev[("/dev/input<br/>linux device")]
end

subgraph group_sim["Simulation"]
  node_object["Car state<br/>state model<br/>[object.c]"]
  node_physics{{"Physics<br/>motion model<br/>[physics.c]"}}
end

subgraph group_view["Rendering"]
  node_render["Render<br/>presentation<br/>[render.c]"]
end

node_inputdev -->|"events"| node_keyhold
node_keyhold -->|"input state"| node_main
node_main -->|"forces"| node_physics
node_physics -->|"updates"| node_object
node_main -->|"reads/writes"| node_object
node_object -->|"frame state"| node_render
node_main -->|"draw"| node_render
node_keyhold -.->|"control intent"| node_object

click node_main "https://github.com/shfahimdev/formulanegativeone/blob/main/main.c"
click node_keyhold "https://github.com/shfahimdev/formulanegativeone/blob/main/keyhold.c"
click node_object "https://github.com/shfahimdev/formulanegativeone/blob/main/object.c"
click node_physics "https://github.com/shfahimdev/formulanegativeone/blob/main/physics.c"
click node_render "https://github.com/shfahimdev/formulanegativeone/blob/main/render.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_keyhold,node_inputdev toneBlue
class node_object,node_physics toneAmber
class node_render toneMint
```

## Components

### Control loop

Main orchestration and asynchronous input capture.

- [Main loop](https://github.com/shfahimdev/formulanegativeone/blob/main/main.c): orchestrator · Runs the fixed-rate update loop and coordinates input, physics, and rendering. · `main.c`
- [Keyhold](https://github.com/shfahimdev/formulanegativeone/blob/main/keyhold.c): input reader · Background-thread keyboard reader that tracks key hold duration via /dev/input. · `keyhold.c`
- **/dev/input**: linux device · Kernel input event source read by the keyboard listener.

### Simulation

Shared vehicle state and physics integration.

- [Car state](https://github.com/shfahimdev/formulanegativeone/blob/main/object.c): state model · Rigid-body vehicle state shared across control, physics, and rendering. · `object.c`
- [Physics](https://github.com/shfahimdev/formulanegativeone/blob/main/physics.c): motion model · Applies forces, friction, and Euler integration on the 2D plane. · `physics.c`

### Rendering

Presentation boundary consuming simulation state.

- [Render](https://github.com/shfahimdev/formulanegativeone/blob/main/render.c): presentation · Consumes simulation state and presents the current frame. · `render.c`

## Connections

- /dev/input → Keyhold: events · Keyboard events are streamed from the Linux input device.
- Keyhold → Main loop: input state · The main loop polls the latest hold durations and key state.
- Main loop → Physics: forces · Main translates controls into forces and advances the simulation.
- Physics → Car state: updates · Physics mutates the shared vehicle state through integration.
- Main loop → Car state: reads/writes · Main uses the state as the boundary between input interpretation and simulation.
- Car state → Render: frame state · Rendering consumes the updated vehicle state.
- Main loop → Render: draw · Each tick ends by handing the current state to the renderer.
- Keyhold → Car state: control intent · Continuous key holds are mapped into movement intent before physics.