# akaash-kashyap/okapilib architecture

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

- Interactive diagram: https://gitdiagram.com/akaash-kashyap/okapilib
- Repository: https://github.com/akaash-kashyap/okapilib

## Overview

##### Project type and purpose
- OkapiLib is an open-source, C++ robotics library built on top of the PROS V5 runtime.
- Its goal is to provide a higher-level, modular API for controlling VEX V5 robot subsystems (chassis, motors, sensors, math utilities), while exposing PROS underpinnings for low-level hardware access.

##### File structure
- Top-level:
– include/okapi & include/display: Public headers (API) for chassis, control, device, filter, odometry, units, utility, plus an LVGL display wrapper.
– src/api: One-to-one implementation of the public API.
– src/impl: Internal implementations and factories for controllers, devices, filters, utilities.
– src/pathfinder & include/pathfinder: Embedded motion-profile trajectory generator/follower code.
– firmware/: Linker scripts and precompiled PROS libs for target hardware.
– CMakeLists.txt, Makefile, common.mk: Build and configuration orchestrators.
– docs/ & Doxyfile: API documentation and tutorials.
– test/ & src/test/ & include/test/: Unit and integration tests for API and impl.

##### Key insights from README
- Emphasis on extensibility, ease-of-use at the API layer, and zero-overhead low-level control.
- SemVer versioning, CONTRIBUTING guidelines, and GitHub Pages for docs.

a. Main components
1. User Code Layer
– User’s main.cpp and PROS project code imports OkapiLib headers.
2. Okapi API Layer (include/okapi, include/display)
– Facade classes: ChassisController, Async/Iterative controllers, Device wrappers, Filters, Odometry, Units, Utility.
3. Okapi Impl Layer (src/impl)
– Factories, builder patterns, default hardware bindings (ADI, motors, sensors), controller runner, time util.
4. Pathfinder Subsystem (include/pathfinder & src/pathfinder)
– Trajectory generation, follower algorithms (tank, swerve), I/O helpers.
5. PROS Runtime & Hardware Layer (firmware/, include/pros)
– Real-time OS, low-level drivers for motor ports, sensors, controller I/O.
6. Documentation & CI
– docs/, .github/workflows, Doxygen, tests, code coverage.

b. Relationships & interactions
- User Code → Okapi API: calls high-level methods to create controllers, send move commands.
- Okapi API → Okapi Impl: API objects delegate to builders and factories in impl.
- Controllers/Filters → PROS: Impl objects call into PROS C-API (via coreProsAPI.hpp) to read sensors, set motor voltages, schedule tasks.
- Pathfinder → Okapi API & Impl: Exposed as part of API/util, used by motion profile controllers.
- Tests → API & Impl: invoke public API and mock or stub impl to verify correctness.
- CI & Docs: monitor and publish status.

c. Architectural patterns & principles
- Layered Architecture: clear separation between API, implementation, and hardware.
- Facade & Builder Patterns: controllers and chassis builders simplify complex setup.
- Dependency Injection/Mocking: implMocks and FakeIt in tests.
- Zero-overhead Abstraction: public headers inline small adapter classes.

d. Key technologies & frameworks
- CMake & Makefiles for cross-platform build.
- PROS V5 real-time OS and C++ runtime.
- LVGL for display UI.
- Conan/Eigen not used—pure C/C++ code.
- Doxygen & m.css for API docs.
- FakeIt & snowhouse for unit tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code Layer
    subgraph "User Code Layer"
        UserCode["src/main.cpp\nUser Code"]:::user
    end

    %% Okapi API Layer
    subgraph "Okapi API Layer"
        APIheaders["Public Headers\ninclude/okapi"]:::api
        Display["Display Wrapper\ninclude/display"]:::api
        APIimpl["API Implementation\nsrc/api"]:::api
    end

    %% Okapi Impl Layer
    subgraph "Okapi Impl Layer"
        ImplDir["Internal Factories & Hardware Adapters\nsrc/impl"]:::impl
        ImplHeaders["Public Inline Impl Headers\ninclude/okapi/impl"]:::impl
    end

    %% Pathfinder Subsystem
    subgraph "Pathfinder Subsystem"
        PFapi["API Headers\ninclude/okapi/pathfinder"]:::path
        PFimpl["C Implementation\nsrc/pathfinder"]:::path
    end

    %% PROS Runtime & Hardware Layer
    subgraph "PROS Runtime & Hardware"
        Firmware["Linker Scripts & Precompiled Libs\nfirmware/"]:::pros
        PROSapi["PROS C-API Headers\ninclude/pros"]:::pros
    end

    %% Tests, Docs & CI
    subgraph "Tests, Docs & CI"
        Tests["Unit & Integration Tests\ntest/ & src/test/"]:::docs
        Docs["Documentation & Tutorials\ndocs/"]:::docs
        CI["CI Workflows\n.github/workflows"]:::docs
    end

    %% Connections
    UserCode -->|"uses API"| APIheaders
    UserCode -->|"uses Display"| Display
    APIheaders -->|"implemented by"| APIimpl
    APIimpl -->|"delegates to"| ImplDir
    APIimpl -->|"inlines to"| ImplHeaders
    ImplDir -->|"calls C-API"| PROSapi
    ImplHeaders -->|"calls C-API"| PROSapi
    PROSapi -->|"interacts with"| Firmware
    APIheaders -->|"utilizes"| PFapi
    PFapi -->|"implemented by"| PFimpl
    PFimpl -->|"depends on"| ImplDir
    Tests -->|"tests"| APIheaders
    Tests -->|"tests"| ImplDir
    CI -->|"runs tests"| Tests
    CI -->|"publishes docs"| Docs
    Docs -->|"documents API"| APIheaders

    %% Click Events
    click UserCode "https://github.com/akaash-kashyap/okapilib/blob/master/src/main.cpp"
    click APIheaders "https://github.com/akaash-kashyap/okapilib/tree/master/include/okapi"
    click Display "https://github.com/akaash-kashyap/okapilib/tree/master/include/display"
    click APIimpl "https://github.com/akaash-kashyap/okapilib/tree/master/src/api"
    click ImplDir "https://github.com/akaash-kashyap/okapilib/tree/master/src/impl"
    click ImplHeaders "https://github.com/akaash-kashyap/okapilib/tree/master/include/okapi/impl"
    click PFapi "https://github.com/akaash-kashyap/okapilib/tree/master/include/okapi/pathfinder"
    click PFimpl "https://github.com/akaash-kashyap/okapilib/tree/master/src/pathfinder"
    click Firmware "https://github.com/akaash-kashyap/okapilib/tree/master/firmware/"
    click PROSapi "https://github.com/akaash-kashyap/okapilib/tree/master/include/pros"
    click Docs "https://github.com/akaash-kashyap/okapilib/tree/master/docs/"
    click CI "https://github.com/akaash-kashyap/okapilib/tree/master/.github/workflows"
    click Tests "https://github.com/akaash-kashyap/okapilib/tree/master/test/"

    %% Styles
    classDef api fill:#cce5ff,stroke:#2a6f97,color:#000;
    classDef impl fill:#d4edda,stroke:#3c763d,color:#000;
    classDef path fill:#fff3cd,stroke:#8a6d3b,color:#000;
    classDef pros fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef docs fill:#f8f9fa,stroke:#343a40,stroke-dasharray: 5 5,color:#000;
    classDef user fill:#d1ecf1,stroke:#0c5460,color:#000;
```
