# f1tenth/f1tenth_planning architecture

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

- Interactive diagram: https://gitdiagram.com/f1tenth/f1tenth_planning
- Repository: https://github.com/f1tenth/f1tenth_planning

## Overview

##### Core Components
- Motion Planning Modules:
- Planning algorithms: fgm, graph planner, lane switcher, lattice planner, wall follow.
- Control algorithms: dynamic MPC, kinematic MPC, LQR, pure pursuit, Stanley.
- Utility Components:
- Utilities (logging, visualization, helper functions) found in the utils folder.
- Examples:
- Example scripts and configuration files that showcase how to use the control and planning modules.
- Documentation:
- The docs folder contains the Sphinx-based documentation with custom extensions, static assets, and example tutorials.
- Configuration & Setup:
- Configuration and setup files (requirements.txt, setup.py, LICENSE, etc.) that define dependencies and package information.

##### Relationships and Interactions
- The f1tenth_planning package is the core of the system, housing the organized control and planning algorithms.
- The control components have a natural connection with the planning components: planning algorithms generate desired paths and trajectories that are then refined or executed by the control algorithms.
- Utility modules support both these main categories by providing logging, visualization, and shared functionalities.
- The examples serve as an integration layer that demonstrates the usage of both control and planning modules in a real scenario.
- The documentation system wraps all these components, showing usage guides and detailed descriptions.

##### Architectural Patterns and Design Principles
- Modularity: Each algorithm (both in control and planning) is contained in its own sub-package, clearly encapsulating its functionality.
- Separation of Concerns: The division between control and planning modules allows each to be maintained, tested, and extended independently.
- Reusability: The use of a shared utils package indicates attention to code reuse (especially in logging and visualization).
- Integration with third-party tools: The Sphinx documentation with custom extensions suggests an intent to provide rich, integrated documentation to support ease of understanding and extension.

##### Relevant Technologies, Frameworks, or Libraries
- Python – the entire project is built in Python.
- Sphinx – used for generating documentation (as seen in docs/, custom Sphinx extensions, etc.).
- Possibly simulation tools or ROS (not explicitly mentioned but commonly paired with F1TENTH)—if applicable, note extensions or integration.
- Standard libraries for robotics motion planning might be indirectly referenced through algorithm implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Setup"
        config["Configuration & Setup"]
    end

    subgraph "Documentation"
        docs["Documentation"]
    end

    subgraph "Core Modules"
        subgraph "Control Module"
            dynamicMPC["Dynamic MPC"]
            kinematicMPC["Kinematic MPC"]
            lqr["LQR"]
            purePursuit["Pure Pursuit"]
            stanley["Stanley"]
        end
        subgraph "Planning Module"
            fgm["FGM"]
            graphPlanner["Graph Planner"]
            laneSwitcher["Lane Switcher"]
            latticePlanner["Lattice Planner"]
            wallFollow["Wall Follow"]
        end
    end

    utilities(("Utilities"))
    examples(("Examples"))

    %% Relationships
    config --> configToDocs[ ]
    config --> dynamicMPC
    config --> fgm

    fgm -->|"trajectory"| dynamicMPC

    dynamicMPC --> utilities
    fgm --> utilities

    examples --> dynamicMPC
    examples --> fgm

    dynamicMPC --> docs
    fgm --> docs

    %% Click Events for Control Algorithms
    click dynamicMPC "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/control/dynamic_mpc/dynamic_mpc.py"
    click kinematicMPC "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/control/kinematic_mpc/kinematic_mpc.py"
    click lqr "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/control/lqr/lqr.py"
    click purePursuit "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/control/pure_pursuit/pure_pursuit.py"
    click stanley "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/control/stanley/stanley.py"

    %% Click Events for Planning Algorithms
    click fgm "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/planning/fgm/fgm.py"
    click graphPlanner "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/planning/graph_planner/graph_planner.py"
    click laneSwitcher "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/planning/lane_switcher/lane_switcher.py"
    click latticePlanner "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/planning/lattice_planner/lattice_planner.py"
    click wallFollow "https://github.com/f1tenth/f1tenth_planning/blob/main/f1tenth_planning/planning/wall_follow/wall_follow.py"

    %% Click Event for Utilities (Directory contains loggers, utils, visualize)
    click utilities "https://github.com/f1tenth/f1tenth_planning/tree/main/f1tenth_planning/utils"

    %% Click Event for Examples
    click examples "https://github.com/f1tenth/f1tenth_planning/tree/main/examples"

    %% Click Event for Documentation
    click docs "https://github.com/f1tenth/f1tenth_planning/tree/main/docs"

    %% Click Event for Configuration & Setup (using setup.py as reference)
    click config "https://github.com/f1tenth/f1tenth_planning/blob/main/setup.py"

    %% Styles
    classDef control fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef planning fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef utilities fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef examples fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef docs fill:#F0B27A,stroke:#D35400,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;

    class dynamicMPC,kinematicMPC,lqr,purePursuit,stanley control;
    class fgm,graphPlanner,laneSwitcher,latticePlanner,wallFollow planning;
    class utilities utilities;
    class examples examples;
    class docs docs;
    class config config;
```
