# theangryraven/doveslaptimer architecture

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

- Interactive diagram: https://gitdiagram.com/theangryraven/doveslaptimer
- Repository: https://github.com/theangryraven/doveslaptimer

## Overview

##### Main components
- Library Core: represented by the files in the “src” folder (DovesLapTimer.cpp and DovesLapTimer.h). This is where the lap timing logic, interpolation, and state management live.
- Example Applications: the Arduino sketches inside “examples” (e.g., basic_oled_example and real_track_data_debug) that demonstrate how to use the library. Note that one example uses a display (basic OLED example) and another uses serial-only data debugging.
- External Hardware Components:
- GPS: The module handling positional data (with support for different GPS hardware specified in the README).
- OLED or other compatible display used in demos.
- Microcontroller: The project is intended for devices like the Seed NRF52840 or even an Arduino Mega+, with specific requirements due to floating-point math.
- Simulation/Emulation: Represented by the “wokwi” folder, which includes simulation configuration (chip json/c files) for in-browser demos.
- Dependencies/External Libraries: Include components like Adafruit_GPS, Adafruit-GFX-Library, Adafruit_SSD1306, and Adafruit_SH110x, which are used in the examples to support hardware functions.

##### Relationships and interactions
- The GPS Module feeds real-time data (latitude, longitude, altitude, speed) into the timing system.
- The Example Application (sketch) acts as the orchestrator—receiving this data and interfacing with the Lap Timer library by calling its initialize, update, and loop methods (as shown in the API usage examples).
- The Lap Timer module internally processes the incoming data, determines if the vehicle has crossed the start/finish line, and computes lap times using interpolation methods.
- Depending on the sketch, processed data may be output to either a display (OLED) or the serial console for debugging.
- In simulation environments (Wokwi), the “wokwi” components simulate the behavior of the GPS firmware to demonstrate how the system works without actual hardware.

##### Important architectural patterns/design principles
- Modular Design: The core functionality is separated into a reusable library (src) while demonstration code resides in examples.
- Hardware Abstraction: The library is independent of any specific hardware, assuming the user will supply proper GPS data and handle any display output.
- Interpolation & Real-Time Processing: The use of multiple interpolation strategies (linear and CatmullRom) to get an accurate crossing time hints at careful algorithmic design.
- API-Driven Development: The API provided (initialize, loop, reset, data retrieval functions) gives a clear abstraction for how the library should be integrated into a host project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Components
    subgraph "Hardware Components"
        GPS["\"GPS Module\""]:::hardware
        MCU["\"Microcontroller\""]:::hardware
        Output["\"Display/Serial Output\""]:::hardware
    end

    %% Demo Applications
    subgraph "Demo Applications"
        subgraph "OLED Display Demo"
            OLED_INO["\"basic_oled_example.ino\""]:::demo
            displayConfig["\"display_config.h\""]:::demo
            gpsConfig["\"gps_config.h\""]:::demo
            images["\"images.h\""]:::demo
            OLED_INO --> displayConfig
            OLED_INO --> gpsConfig
            OLED_INO --> images
        end
        subgraph "Serial Debug Demo"
            Serial_INO["\"real_track_data_debug.ino\""]:::demo
        end
    end

    %% Library Core
    subgraph "Library Core"
        LapTimerCPP["\"DovesLapTimer.cpp\""]:::library
        LapTimerH["\"DovesLapTimer.h\""]:::library
        LapTimerCPP --- LapTimerH
    end

    %% Simulation Module
    subgraph "Simulation Module"
        SimC["\"gps-fake.chip.c\""]:::simulation
        SimJSON["\"gps-fake.chip.json\""]:::simulation
        SimC --- SimJSON
    end

    %% Dependency Management
    Dependency["\"library.properties\""]:::dependency

    %% Data Flow Connections
    GPS -->|"feedsGPSdata"| OLED_INO
    GPS -->|"feedsGPSdata"| Serial_INO
    SimC ---|"simulatesGPS"| OLED_INO
    SimJSON ---|"simulatesGPS"| Serial_INO

    MCU -->|"runsSkecthes"| OLED_INO
    MCU -->|"runsSkecthes"| Serial_INO

    OLED_INO -->|"callsAPI_initialize_loop"| LapTimerCPP
    Serial_INO -->|"callsAPI_initialize_loop"| LapTimerCPP

    LapTimerCPP -->|"processesLapTimes"| Output

    Dependency -->|"configures"| LapTimerCPP

    %% Styles
    classDef hardware fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef demo fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef library fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef simulation fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef dependency fill:#FFA07A,stroke:#333,stroke-width:2px;

    %% Click Events
    click LapTimerCPP "https://github.com/theangryraven/doveslaptimer/blob/master/src/DovesLapTimer.cpp"
    click LapTimerH "https://github.com/theangryraven/doveslaptimer/blob/master/src/DovesLapTimer.h"
    click OLED_INO "https://github.com/theangryraven/doveslaptimer/blob/master/examples/basic_oled_example/basic_oled_example.ino"
    click displayConfig "https://github.com/theangryraven/doveslaptimer/blob/master/examples/basic_oled_example/display_config.h"
    click gpsConfig "https://github.com/theangryraven/doveslaptimer/blob/master/examples/basic_oled_example/gps_config.h"
    click images "https://github.com/theangryraven/doveslaptimer/blob/master/examples/basic_oled_example/images.h"
    click Serial_INO "https://github.com/theangryraven/doveslaptimer/blob/master/examples/real_track_data_debug/real_track_data_debug.ino"
    click SimC "https://github.com/theangryraven/doveslaptimer/blob/master/wokwi/gps-fake.chip.c"
    click SimJSON "https://github.com/theangryraven/doveslaptimer/blob/master/wokwi/gps-fake.chip.json"
    click Dependency "https://github.com/theangryraven/doveslaptimer/blob/master/library.properties"
```
