Hyper-K

This high-level architecture demonstrates the decoupled nature of the system:

The "Remote Asset" (Python): Simulates the physical physics.

The "Digital Pit Wall" (Forge FE): Visualizes the data.

The "Race Engineer" (Rovo): Reasons about the data.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#E11D3E', 'secondaryColor': '#f4f4f5', 'tertiaryColor': '#fff', 'mainBkg': '#fcfcfc', 'nodeBorder': '#e5e7eb'}}}%%
graph TD
    subgraph Atlassian_Cloud [Atlassian Cloud Ecosystem]
        JSM[Jira Service Management]
        Rovo[Rovo Agent<br/>'Race Engineer']
        
        subgraph Forge_Platform [Atlassian Forge Runtime]
            Resolver[Forge Resolver<br/>Node.js Lambda]
            CustomUI[Custom UI Frontend<br/>React 19 + R3F]
        end
    end

    subgraph External_Services [External Infrastructure]
        PythonAPI[Physics Simulator<br/>FastAPI / Python]
        GCS[Google Cloud Storage<br/>3D Models .glb]
    end

    %% Data Flow
    User((User/Fleet Manager)) -->|Views Issue| JSM
    JSM -->|Loads Panel| CustomUI
    
    CustomUI -->|Polls Telemetry| Resolver
    Resolver -->|HTTPS GET /telemetry| PythonAPI
    
    CustomUI -->|Streams 3D Asset| GCS
    
    Rovo -->|Action: fetch-telemetry| Resolver
    Rovo -->|Action: create-ticket| JSM
    
    %% Fault Injection
    Admin((Demo Admin)) -->|POST /inject-fault| PythonAPI
    
    style JSM fill:#0052CC,stroke:#fff,color:#fff
    style Rovo fill:#6554C0,stroke:#fff,color:#fff
    style PythonAPI fill:#FFC400,stroke:#333,color:#000
    style CustomUI fill:#36B37E,stroke:#fff,color:#fff

"Your Excavator is the Car. Rovo is the Race Engineer. JSM is the Pit Wall."

Hyper-K is a Digital Twin platform that transposes Formula 1 telemetry strategies onto industrial heavy equipment.

Built for the Komatsu HB365LC-3 Hybrid Excavator, this application addresses the critical "Invisible Heat" problem in regenerative energy systems. By leveraging Atlassian Forge, React Three Fiber, and Rovo Agents, we empower Fleet Managers to visualize thermal stress on a 3D model and utilize AI Agents to negotiate preventative "Pit Stops" before catastrophic failure occurs.

The solution utilizes a decoupled architecture to handle high-frequency physics simulation outside of the Atlassian tenant, while keeping the user experience deeply integrated within Jira.

• Host: Atlassian Forge (Custom UI)
• Frontend: React 19, React Three Fiber (drei), Tailwind CSS v4, Shadcn/UI
• Intelligence: Atlassian Rovo (rovo:agent)
• Simulation Engine: Python 3.11, FastAPI (Deployed on Google Cloud Run)
• Storage: Google Cloud Storage (Hosting high-fidelity GLTF models)

A high-fidelity Digital Twin rendered directly inside a Jira Service Management Issue Panel.

• Dynamic Heatmap Shader: The 3D model's Ultra-Capacitor glows from Green (Safe) to Red (Critical) based on real-time physics data.
• GCS Bypass: Loads large 3D assets (>10MB) from external cloud storage to bypass Forge bundle limits while maintaining performance.
• Glassmorphism UI: A "Williams Racing" aesthetic data overlay built with Tailwind v4.

A Python-based engine that models the Komatsu Hybrid System.

• Regen vs. Assist Logic: Simulates voltage rise during braking and voltage drop during digging.
• Chaos Monkey Endpoint: A dedicated API route to force a "Thermal Runaway" event for demonstration purposes.

An Agent grounded in the "Komatsu Technical Manual".

• Chain of Thought: Analyzes "Rate of Rise" ($RoR$) to predict failure before absolute thresholds are breached.
• Autonomous Action: Can autonomously create High-Priority Incident tickets in JSM when risks are detected.

This repository is a monorepo containing both the Atlassian Forge App and the Python Backend.

• Node.js (v22+) & npm
• Python 3.11
• Atlassian Forge CLI (npm install -g @forge/cli)
• A Google Cloud Storage bucket (for the 3D model)

1. Navigate to the backend directory:

   cd hyper-k-backend

2. Install dependencies:

   pip install -r requirements.txt

3. Run the server locally:

   uvicorn main:app --reload --port 8000

   • The API will be available at http://localhost:8000

1. Navigate to the UI directory:

   cd static/hyper-k-ui

2. Install dependencies and build the React 19 app:

   npm install
   npm run build

   • This generates the /dist folder required by Forge.
3. Navigate back to the app root:

   cd ../..

4. Login and Register the app:

   forge login
   forge register

5. Deploy to your Atlassian Development Environment:

   forge deploy
   forge install

   • Select "Jira Service Management" when prompted.

Scenario: We will simulate a cooling pump failure leading to a thermal runaway event.

1. Open Jira: Navigate to any Issue in your JSM project. Open the "Hyper-K Telemetry Twin" panel.
   • Status: You should see the excavator in a Green/Nominal state.
2. Trigger the Fault (Chaos Monkey):
   • Send a POST request to your backend:

   curl -X POST [https://your-backend-url.com/simulation/HB-044/inject-fault](https://your-backend-url.com/simulation/HB-044/inject-fault)

3. Witness the Failure:
   • The 3D model in Jira will begin to glow Red.
   • The HUD status will flip to CRITICAL.
4. Engage Rovo:
   • Open Rovo Chat in Jira.
   • Ask: "Check status of Unit HB-044."
   • Rovo will analyze the data, detect the 90°C spike, and recommend a "Box Box" (Pit Stop).
   • Command: "Create ticket."
5. Resolution:
   • Rovo generates a new Incident ticket with the diagnostic snapshot attached.

hyper-k-telemetry/
├── manifest.yml                # Forge Config & Permissions
├── src/
│   └── index.js                # Forge Resolvers (Node.js)
├── static/
│   └── hyper-k-ui/             # React 19 Frontend
│       ├── src/
│       │   ├── components/3d/  # R3F Excavator Models
│       │   └── index.css       # Tailwind v4 Theme
│       └── vite.config.ts      # Build Config
└── hyper-k-backend/            # Python Simulator
    └── main.py                 # FastAPI App


📄 License

This project is licensed under the MIT License - see the LICENSE file for details.