# danielenapo/rubik-s-cube-solver architecture

> Architecture diagram of the GitHub repository danielenapo/rubik-s-cube-solver, 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/danielenapo/rubik-s-cube-solver
- Repository: https://github.com/danielenapo/rubik-s-cube-solver

## Overview

##### Project type and purpose
- This is a standalone full-client Android application whose responsibilities are:
– Capturing cube face images via camera (OpenCV)
– Computing optimal solution moves (Kociemba’s algorithm via min2phase)
– Rendering a 3D animated cube and step-by-step moves (OpenGL/Android views)

##### File structure
- app/ – Android application module
– src/main/java/cs/min2phase → solver engine (CoordCube, Search, Tools)
– src/main/java/com/example/mostraMosse → 3D cube model, renderer, view, UI activities
– src/main/java/com/example/menu & Instructions → launch screens, menus
– src/main/cpp & jniLibs → native stubs and prebuilt OpenCV native libs for image processing
- java/ – OpenCV SDK module
– src/main/java/org/opencv → wrappers & AIDL interfaces for OpenCV camera and image-processing APIs

##### README for insights
- Technologies: OpenCV (Java + native), OpenGL ES (Android GLWorld/CubeRenderer), Kociemba’s algorithm, Android SDK

##### Main components & relationships

A. Camera & Capture Layer
– Android Camera API (JavaCameraView)
– OpenCVLoader & BaseLoaderCallback
– AsyncServiceHelper (initialization)

→ feeds frames to →

B. Scanner Module
– Scanner.java & Square.java

→ passes ‘state’ to →

C. Solver Engine
– min2phase.Search & CoordCube/CubieCube
– Tools & Util for move sequence generation
– Outputs ordered list of moves (e.g. “R U R’ U’…”)

→ sends moves to →

D. Visualization Module
– GLWorld, CubeRenderer, CubeView
– RubeCube, CubeSide, Layer data models
– DragThread for user interaction
– MostraMosseActivity / MostraMosseApp UI

E. Menu & Navigation
– Menu.java, Instructions.java
– Launch flow: Menu → ScannerActivity → Solver→ VisualizationActivity

F. External Dependencies (outside Android APK)
– OpenCV native libs (.so in jniLibs)
– OpenCV AIDL service (OpenCVEngineInterface)

##### Architectural patterns
- Modular layering: capture → processing → business logic → presentation
- MVC-style separation in visualization module: data (RubeCube) vs. view (CubeView) vs. controller (DragThread)
- Native/Java boundary: OpenCV native libs ↔ Java wrappers (via JNI/AIDL)

##### Detail without over-fragmenting
- Logical modules above
- Inside each module, you may list key classes in small font
- Do not break down into individual utility classes (e.g., Converters, Util), unless they play a major architectural role

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Capture Layer
    subgraph "Camera & Capture Layer"
        JCV["JavaCameraView"]:::android
        OCL["OpenCVLoader"]:::android
        BLCB["BaseLoaderCallback"]:::android
        ASH["AsyncServiceHelper"]:::android
    end

    %% Scanner Module
    subgraph "Scanner Module"
        SC["Scanner.java"]:::custom
        SQ["Square.java"]:::custom
    end

    %% Solver Engine
    subgraph "Solver Engine"
        CC["CoordCube.java"]:::custom
        CB["CubieCube.java"]:::custom
        SR["Search.java"]:::custom
        TL["Tools.java"]:::custom
        UT["Util.java"]:::custom
    end

    %% Visualization Module
    subgraph "Visualization Module"
        GW["GLWorld.java"]:::custom
        CR["CubeRenderer.java"]:::custom
        CV["CubeView.java"]:::custom
        CU["Cube.java"]:::custom
        RC["RubeCube.java"]:::custom
        CS["CubeSide.java"]:::custom
        LY["Layer.java"]:::custom
        DT["DragThread.java"]:::custom
        MA["MostraMosseActivity"]:::android
        MP["MostraMosseApp"]:::android
    end

    %% Menu & Navigation
    subgraph "Menu & Navigation"
        MN["Menu.java"]:::android
        IN["Instructions.java"]:::android
        LM["activity_menu.xml"]:::android
        LI["activity_instructions.xml"]:::android
    end

    %% External Dependencies
    subgraph "External Dependencies"
        SO["OpenCV .so libs"]:::native
        CPP["CMakeLists.txt & dummy-lib.cpp"]:::native
        AIDL["OpenCVEngineInterface.aidl"]:::native
    end

    %% Connections
    JCV -->|Frame → Mat| SC
    OCL -->|init| JCV
    BLCB -->|callback| OCL
    ASH -->|service init| BLCB
    SC -->|Color array| CC
    SC -->|Color array| CB
    SC -->|Color array| SR
    CC -->|coords| SR
    CB -->|coords| SR
    SR -->|move list| GW
    TL -->|helper| SR
    UT -->|util| SR
    GW -->|render| CV
    CR -->|draw| CV
    CV -->|touch→ Drag| DT
    DT -->|gesture| CV
    MA -->|UI| GW
    MP -->|app| MA
    MN -->|launch| JCV
    MN -->|menu→Scanner| SC
    IN -->|instructions| MN
    MP -->|nav| IN
    SO -->|native processing| SC
    SO -->|native image processing| OCL
    CPP -->|JNI bridge| OCL
    AIDL -->|AIDL interface| OCL

    %% Click Events
    click JCV "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/java/src/main/java/org/opencv/android/JavaCameraView.java"
    click OCL "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/java/src/main/java/org/opencv/android/OpenCVLoader.java"
    click BLCB "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/java/src/main/java/org/opencv/android/BaseLoaderCallback.java"
    click ASH "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/java/src/main/java/org/opencv/android/AsyncServiceHelper.java"
    click SC "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/scanner/Scanner.java"
    click SQ "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/scanner/Square.java"
    click CC "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/cs/min2phase/CoordCube.java"
    click CB "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/cs/min2phase/CubieCube.java"
    click SR "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/cs/min2phase/Search.java"
    click TL "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/cs/min2phase/Tools.java"
    click UT "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/cs/min2phase/Util.java"
    click GW "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/GLWorld.java"
    click CR "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/CubeRenderer.java"
    click CV "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/CubeView.java"
    click CU "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/Cube.java"
    click RC "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/RubeCube.java"
    click CS "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/CubeSide.java"
    click LY "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/Layer.java"
    click DT "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/DragThread.java"
    click MA "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/MostraMosseActivity.java"
    click MP "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/mostraMosse/MostraMosseApp.java"
    click MN "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/menu/Menu.java"
    click IN "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/java/com/example/menu/Instructions.java"
    click LM "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/res/layout/activity_menu.xml"
    click LI "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/res/layout/activity_instructions.xml"
    click SO "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/jniLibs/arm64-v8a/*.so"
    click CPP "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/cpp/CMakeLists.txt"
    click CPP "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/app/src/main/cpp/dummy-lib.cpp"
    click AIDL "https://github.com/danielenapo/rubik-s-cube-solver/blob/master/java/src/main/aidl/org/opencv/engine/OpenCVEngineInterface.aidl"

    %% Styles
    classDef android fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef custom fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef native fill:#FFE0B2,stroke:#333,stroke-width:1px
```
