# Layout

## Code Structure

### Architecture (Summary)

<span style="white-space: pre-wrap;">Each board’s </span>`<span class="editor-theme-code">main.c</span>`<span style="white-space: pre-wrap;"> acts strictly as an orchestrator. It initializes the runtime, creates tasks, and delegates all functional behavior to component modules.</span>

### Core Design Contract

<span style="white-space: pre-wrap;">The repository enforces a strict separation between </span>**entrypoints**<span style="white-space: pre-wrap;"> and </span>**components**:

- `<span class="editor-theme-code">src/<board>/main.c</span>`<span style="white-space: pre-wrap;"> defines the process entrypoint for each board target.</span>
- `<span class="editor-theme-code">components/common/*</span>`<span style="white-space: pre-wrap;"> contains reusable logic shared across multiple boards.</span>
- `<span class="editor-theme-code">components/<board>/*</span>`<span style="white-space: pre-wrap;"> contains board-specific functionality.</span>
- `<span class="editor-theme-code">components/<board>/firmware/*</span>`<span style="white-space: pre-wrap;"> contains generated or vendor-provided firmware and MCU integration code.</span>

### Primary Rule

> `<span class="editor-theme-code">main.c</span>`<span style="white-space: pre-wrap;"> must not contain domain logic. It is responsible only for system wiring and task startup.</span>
> 
> \- Albert Einstein

## Repository Layout

```
erc/
├─ src/
│  ├─ arm_board/main.c
│  ├─ driving_board/main.c
│  ├─ sensor_board/main.c
│  ├─ network_board/main.c
│  └─ debugging_board/main.c
│
├─ components/
│  ├─ common/              # Shared modules across boards
│  ├─ arm_board/           # Arm board-specific modules
│  ├─ driving_board/       # Driving board-specific modules
│  ├─ sensor_board/        # Sensor board-specific modules
│  ├─ network_board/       # Network board-specific modules
│  └─ debugging_board/     # Debugging board-specific modules
│
├─ test/
│  ├─ common/
│  ├─ arm_board/
│  ├─ driving_board/
│  ├─ sensor_board/
│  └─ debugging_board/
│
├─ scripts/                # Utility scripts (codegen, post-processing)
└─ platformio.ini          # Build environments and board filters
```

## Entrypoint Responsibilities (`<span class="editor-theme-code">src/<board>/main.c</span>`)

<span style="white-space: pre-wrap;">The </span>`<span class="editor-theme-code">main.c</span>`<span style="white-space: pre-wrap;"> file is intentionally minimal and should perform only the following:</span>

1. Execute mandatory low-level initialization  
    **(HAL, clock, cache, MPU, RTOS initialization as required)**
2. Initialize infrastructure dependencies  
    **(GPIO, UART, timers, networking wrappers, etc.)**
3. Create one or more RTOS tasks
4. Start the scheduler/kernel
5. Delegate all functional behavior to components

### <span style="white-space: pre-wrap;">What Must NOT Be Implemented in </span>`<span class="editor-theme-code">main.c</span>`

<span style="white-space: pre-wrap;">The following must never reside in </span>`<span class="editor-theme-code">main.c</span>`:

- Sensor processing algorithms
- Business or control logic
- Packet parsing or dispatch policy
- Device-specific runtime behavior beyond initialization
- Long-running loops implementing application logic

If logic grows beyond simple initialization or task creation, it must be moved into a component module and invoked from a task.

## Component Responsibilities (`<span class="editor-theme-code">components/*</span>`)

All functional behavior belongs in components. Tasks must delegate to components rather than implementing logic inline.

### Examples

- <span style="white-space: pre-wrap;">Sensor-related behavior → </span>`<span class="editor-theme-code">components/sensor_board/*</span>`  
    **(e.g., GPS, IMU, pH sensors, acquisition pipelines)**
- <span style="white-space: pre-wrap;">Driving logic → </span>`<span class="editor-theme-code">components/driving_board/*</span>`  
    **(e.g., motor control, calculations, protocol parsing, Simulink integration)**
- <span style="white-space: pre-wrap;">Debugging UI and diagnostics → </span>`<span class="editor-theme-code">components/debugging_board/*</span>`
- <span style="white-space: pre-wrap;">Shared infrastructure → </span>`<span class="editor-theme-code">components/common/*</span>`  
    **(e.g., result handling, logging, queues, dispatch systems)**

## Execution Model

The execution flow for each board follows a consistent structure:

```
main.c
  → platform/runtime initialization
  → create RTOS task(s)
  → each task calls component APIs
  → component modules execute all functional logic
```

This ensures that:

- `<span class="editor-theme-code">main.c</span>`<span style="white-space: pre-wrap;"> remains stable and minimal</span>
- behavior is modular and testable
- functionality is reusable across boards