# alberthli/frogger architecture

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

- Interactive diagram: https://gitdiagram.com/alberthli/frogger
- Repository: https://github.com/alberthli/frogger

## Overview

##### Project type and purpose
- FRoGGeR is a Python-based computational library/tool for fast, robust grasp generation on robotic hands (Allegro, Barrett, FR3). It is *not* a full-stack web app, but a domain-specific tool that provides an API, CLI scripts, data assets, and example drivers to synthesize grasps via nonlinear optimization.

##### File structure
- Top-level directories:
- data/ : YCB object meshes, collision meshes, and pickled experimental results
- frogger/ : core Python package (modules: objects, robots, sampling, solvers, baselines, metrics, sdfs, utils)
- models/ : URDF/SDF robot descriptions & meshes for Allegro hand, Barrett hand, FR3, FR3+Zed2i
- examples/ : Python scripts demonstrating API usage
- scripts/ : timing.py CLI driver
- environment.yml, pyproject.toml: dependency management
- Key external config: Drake (via pydrake), numba, jax, MOSEK integration (optional), conda.

##### README for additional insights
- The README outlines the three inputs: robot model, object description, initial-guess sampler.
- It references Drake solvers, numba for JIT compilation, and describes how modules mesh.

a. Main components:
1) Client layer (Examples & Scripts)
2) FRoGGeR core API modules:
- Objects (MeshObjectConfig, SDF objects)
- Robots (URDF/SDF parsers & model builders: AlgrModelConfig, Barrett, FR3)
- Samplers (HeuristicAlgrICSampler, custom IC Samplers)
- Solvers (FroggerConfig wrapping nonlinear solver)
- Utilities (timeout, viz_config)
- Baselines & Metrics (optional fallback solvers, f-closure metrics)
3) Data assets:
- data/ directory of object meshes & collision meshes
- models/ directory of robot description files & meshes
- pickled experiment outputs (for benchmarking/comparison)
4) Third-party compute layer:
- Drake (pydrake) for dynamics, collision checking, optimization backends (SNOPT/MOSEK)
- numba (JIT) & jax (if SDF analytic objects)
5) Environment & Build:
- conda environment (environment.yml)
- pip editable install (pyproject.toml)

b. Relationships & interactions:
- Examples/scripts → invoke FRoGGeR API →
- FRoGGeR core modules request meshes and robot descriptions →
- Load object meshes from data/ and robot SDF/URDF from models/ →
- Build Drake MultibodyPlant & SceneGraph →
- Sampler generates initial guess →
- Solver (via Drake MathematicalProgram) performs optimization →
- Results returned (joint angles q_star) →
- Viz utils display the result; pickled for benchmarking.

c. Architectural patterns / design principles:
- Modular package structure: one module per concern (objects, robots, solvers).
- Clear separation of data assets vs. code vs. examples.
- Plugin-style extensibility: custom samplers or object definitions.
- Single-file robot description ensures encapsulation for Drake parser.

d. Relevant technologies:
- Python 3.x, pip, conda
- Drake (pydrake) for simulation and optimization
- numba for JIT-accelerated sampling code
- jax (optional) for analytic SDF objects
- MOSEK integration via Drake license

##### Elements
- Components labeled clearly (Examples, Objects module, Robots module…)
- from examples/scripts to API modules
- from API modules to data assets and to compute backends
- from compute backends back to API and then to UI

##### Final advice
- Be exhaustive: capture all core modules even if they seem minor.
- Keep it at one screen-width: group modules into logical clusters.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        AlgrExample["examples/algr.py"]:::ui
        BHExample["examples/bh280.py"]:::ui
        FR3Example["examples/fr3algr.py"]:::ui
        TimingScript["scripts/timing.py"]:::ui
    end

    %% FRoGGeR Core API
    subgraph "FRoGGeR Core API" 
        direction TB
        Entrypoint["grasping.py (API Entrypoint)"]:::api
        Objects["objects.py"]:::api
        RobotsCore["robot_core.py"]:::api
        Robots["robots.py"]:::api
        Samplers["sampling.py"]:::api
        Solver["solvers.py"]:::api
        Baselines["baselines.py"]:::api
        Metrics["metrics.py"]:::api
        SDFs["sdfs.py"]:::api
        Utils["utils.py"]:::api
    end

    %% Data Assets
    subgraph "Data Assets"
        direction TB
        ObjMeshes["Object Meshes (data/)"]:::data
        RobotModels["Robot Descriptions (models/)"]:::data
    end

    %% Compute Backends
    subgraph "Third-Party Compute"
        direction TB
        Drake["Drake (pydrake)"]:::external
        Numba["numba JIT"]:::external
        JAX["jax"]:::external
        MOSEK["MOSEK"]:::external
    end

    %% Connections: UI to API
    AlgrExample -->|"calls API"| Entrypoint
    BHExample -->|"calls API"| Entrypoint
    FR3Example -->|"calls API"| Entrypoint
    TimingScript -->|"invokes CLI"| Entrypoint

    %% API workflow
    Entrypoint -->|"loads objects"| Objects
    Entrypoint -->|"loads robots"| RobotsCore
    Entrypoint -->|"loads robots"| Robots
    Entrypoint -->|"samples init guess"| Samplers
    Entrypoint -->|"solves optimization"| Solver
    Entrypoint -->|"fallback solver"| Baselines
    Entrypoint -->|"compute metrics"| Metrics
    Entrypoint -->|"SDF analytic"| SDFs
    Entrypoint -->|"viz config"| Utils

    %% Data flows
    Objects -->|"mesh files"| ObjMeshes
    RobotsCore -->|"URDF/SDF"| RobotModels
    Robots -->|"URDF/SDF"| RobotModels

    %% Compute calls
    Objects -->|"collision checking"| Drake
    RobotsCore -->|"plant & scenegraph"| Drake
    Robots -->|"plant & scenegraph"| Drake
    Samplers -->|"JIT compile"| Numba
    SDFs -->|"auto-diff"| JAX
    Solver -->|"mathematical program"| Drake
    Solver -->|"MOSEK backend"| MOSEK

    %% Return flow
    Solver -->|"q_star"| Entrypoint
    Entrypoint -->|"results"| Utils
    Utils -->|"display/pickle"| TimingScript

    %% Click Events
    click AlgrExample "https://github.com/alberthli/frogger/blob/main/examples/algr.py"
    click BHExample "https://github.com/alberthli/frogger/blob/main/examples/bh280.py"
    click FR3Example "https://github.com/alberthli/frogger/blob/main/examples/fr3algr.py"
    click TimingScript "https://github.com/alberthli/frogger/blob/main/scripts/timing.py"
    click Objects "https://github.com/alberthli/frogger/blob/main/frogger/objects.py"
    click RobotsCore "https://github.com/alberthli/frogger/blob/main/frogger/robots/robot_core.py"
    click Robots "https://github.com/alberthli/frogger/blob/main/frogger/robots/robots.py"
    click Samplers "https://github.com/alberthli/frogger/blob/main/frogger/sampling.py"
    click Solver "https://github.com/alberthli/frogger/blob/main/frogger/solvers.py"
    click Baselines "https://github.com/alberthli/frogger/blob/main/frogger/baselines.py"
    click Metrics "https://github.com/alberthli/frogger/blob/main/frogger/metrics.py"
    click SDFs "https://github.com/alberthli/frogger/blob/main/frogger/sdfs.py"
    click Utils "https://github.com/alberthli/frogger/blob/main/frogger/utils.py"
    click Entrypoint "https://github.com/alberthli/frogger/blob/main/frogger/grasping.py"

    %% Styles
    classDef ui fill:#dddddd,stroke:#888888,color:#000000
    classDef api fill:#cee4fd,stroke:#3b7ddd,color:#000000
    classDef data fill:#dfffd6,stroke:#3b9d00,color:#000000
    classDef external fill:#ffe3b3,stroke:#dd8c00,color:#000000
```
