# Solution Architecture

This document outlines common solution architectures and integration patterns
for Jumpstarter, helping you understand how to incorporate it into your
development and testing workflows.

## Common Integration Patterns

Jumpstarter is designed to integrate with various tools and platforms across the
hardware development lifecycle. Here are the key integration points:

- **CI/CD Systems**: Jenkins, GitHub Actions, GitLab CI, Tekton
- **Infrastructure Tools**: Kubernetes, Prometheus, Grafana
- **Development Workflows**: IDEs, shell scripts, Makefiles
- **Testing Frameworks**: pytest, unittest, Robot Framework

## Integration with Infrastructure

### Continuous Integration with System Testing

```{mermaid}
:config: {"theme":"base","themeVariables":{"primaryColor":"#f8f8f8","primaryTextColor":"#000","primaryBorderColor":"#e5e5e5","lineColor":"#3d94ff","secondaryColor":"#f8f8f8","tertiaryColor":"#fff"}}
flowchart TB
    subgraph "Version Control"
        GitRepo["Git Repository"]
        Actions["GitHub/GitLab CI"]
    end

    subgraph "Jumpstarter Infrastructure"
        Controller["Controller"]
        Exporters["Exporter"]
        DUTs["Device Under Test"]
    end

    GitRepo -- "Code changes" --> Actions
    Actions -- "Request access" --> Controller
    Controller -- "Assign lease" --> Actions
    Controller -- "Connect to" --> Exporters
    Exporters -- "Control" --> DUTs
    Actions -- "Update status" --> GitRepo
```

This architecture integrates Jumpstarter with CI/CD pipelines to enable
automated testing on real systems:

1. Code changes trigger the CI pipeline
2. The pipeline runs tests that use Jumpstarter to access systems
3. Jumpstarter's controller manages device access and leases
4. Test results are reported back to the CI system

**CI Configuration Examples:**

<div class="tab-container">
  <div class="tab">
    <button class="tablinks active" onclick="openTab(event, 'GitHub1')">GitHub</button>
    <button class="tablinks" onclick="openTab(event, 'GitLab1')">GitLab</button>
  </div>

  <div id="GitHub1" class="tabcontent" style="display:block;">

```yaml
# .github/workflows/hardware-test.yml
jobs:
  hardware-test:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v3
      - name: Request hardware lease
        run: |
          jmp config client use ci-client
          jmp create lease --selector project=myproject --wait 300
      - name: Run tests
        run: pytest tests/hardware_tests/
      - name: Release hardware lease
        if: always()
        run: jmp delete lease
```

  </div>

  <div id="GitLab1" class="tabcontent">

```yaml
# .gitlab-ci.yml
hardware-test:
  tags:
    - self-hosted
  script:
    - jmp config client use ci-client
    - jmp create lease --selector project=myproject --wait 300
    - pytest tests/hardware_tests/
  after_script:
    - jmp delete lease
```

  </div>
</div>

### Self-Hosted CI Runner with Attached System

```{mermaid}
:config: {"theme":"base","themeVariables":{"primaryColor":"#f8f8f8","primaryTextColor":"#000","primaryBorderColor":"#e5e5e5","lineColor":"#3d94ff","secondaryColor":"#f8f8f8","tertiaryColor":"#fff"}}
flowchart TB
    subgraph "Version Control"
        GitRepo["Git Repository"]
        Actions["GitHub/GitLab CI"]
    end

    subgraph "Runner"
        Runner1["Self-Hosted Runner"]
        JmpLocal["Local Mode"]
        Devices["Device Under Test"]
    end

    GitRepo -- "Code changes" --> Actions
    Actions -- "Dispatch job" --> Runner1
    
    Runner1 -- "Execute tests" --> JmpLocal
    JmpLocal -- "Control" --> Devices
    
    Runner1 -- "Report results" --> Actions
    Actions -- "Update status" --> GitRepo
```

This architecture leverages a self-hosted runner with directly attached system:

1. The self-hosted runner has physical devices connected directly to it
2. Jumpstarter runs in local mode on the runner, controlling the attached system
3. Code changes trigger CI jobs which are dispatched to the runner
4. Tests execute on the runner using Jumpstarter to interface with the system
5. Results are reported back to the CI system

This approach is ideal when:
- System needs to be permanently connected to a specific test machine
- You want to integrate system testing into existing CI/CD workflows without additional infrastructure
- You need a simple setup for initial system-in-the-loop testing

**CI Configuration Examples:**

<div class="tab-container">
  <div class="tab">
    <button class="tablinks active" onclick="openTab(event, 'GitHub2')">GitHub</button>
    <button class="tablinks" onclick="openTab(event, 'GitLab2')">GitLab</button>
  </div>

  <div id="GitHub2" class="tabcontent" style="display:block;">

```yaml
# .github/workflows/self-hosted-hw-test.yml
jobs:
  hardware-test:
    runs-on: self-hosted-hw-attached
    steps:
      - uses: actions/checkout@v3
      - name: Run Jumpstarter in local mode
        run: jmp local start --config=./.jumpstarter/local-config.yaml
      - name: Run tests
        run: pytest tests/hardware_tests/
      - name: Cleanup
        if: always()
        run: jmp local stop
```

  </div>

  <div id="GitLab2" class="tabcontent">

```yaml
# .gitlab-ci.yml
hardware-test:
  tags:
    - hw-attached
  script:
    - jmp local start --config=./.jumpstarter/local-config.yaml
    - pytest tests/hardware_tests/
  after_script:
    - jmp local stop
```

  </div>
</div>

### Cost Management and Chargeback

Organizations can implement usage-based billing for teams through a cost management layer.

```{mermaid}
:config: {"theme":"base","themeVariables":{"primaryColor":"#f8f8f8","primaryTextColor":"#000","primaryBorderColor":"#e5e5e5","lineColor":"#3d94ff","secondaryColor":"#f8f8f8","tertiaryColor":"#fff"}}
flowchart LR
    subgraph "Kubernetes"
        Controller["Controller"]
        
        subgraph "Telemetry"
            Prometheus["Prometheus"]
            Grafana["Grafana"]
            AlertManager["AlertManager"]
        end
        
        subgraph "Cost Management"
            UsageTracker["Usage Tracker"]
            OpenCost["OpenCost"]
            Accounting["Chargeback System"]
        end
    end
    
    subgraph "Lab"
        Rack1["Exporter 1"]
        Rack2["Exporter 2"]
    end

    subgraph "Users"
        Team["Team"]
    end

    Team -- "Request access" --> Controller
    Controller -- "Assign lease" --> Team
    Controller -- "Record lease\nmetadata" --> Prometheus

    Controller -- "Connect to" --> Rack1
    Controller -- "Connect to" --> Rack2
    
    Rack1 -- "Report usage\nmetrics" --> Prometheus
    Rack2 -- "Report usage\nmetrics" --> Prometheus
    
    Prometheus -- "Store\nmetrics" --> Grafana
    Prometheus -- "Threshold\nalerts" --> AlertManager
    Prometheus -- "Usage\nmetrics" --> UsageTracker
    
    UsageTracker -- "Monthly billing\nreport" --> Team
    
    UsageTracker -- "Team resource\nusage" --> OpenCost
    OpenCost -- "Cost\nallocation" --> Accounting
```

This architecture implements a cost chargeback model for infrastructure resources:

1. Prometheus serves as the foundation for collecting and storing all resource utilization metrics
2. The team requests resources through the controller, which records team identifiers with each lease
3. System resources export detailed utilization metrics to Prometheus:
   - Resource uptime and availability
   - Utilization metrics (CPU, memory, I/O)
   - Team attribution via metadata

## Integration with Developer Environments

### Traditional Developer Workflow

```{mermaid}
:config: {"theme":"base","themeVariables":{"primaryColor":"#f8f8f8","primaryTextColor":"#000","primaryBorderColor":"#e5e5e5","lineColor":"#3d94ff","secondaryColor":"#f8f8f8","tertiaryColor":"#fff"}}
flowchart TB
    subgraph "Workstation"
        TestCode["Test Code"]
    end

    subgraph "Local Environment"
        LocalExporter["Local Exporter"]
        DeviceOnDesk["Device Under Test"]
    end

    subgraph "Lab"
        Controller["Controller"]
        RemoteExporters["Exporter"]
        LabDevices["Device Under Test"]
    end
    
    TestCode --> LocalExporter
    LocalExporter --> DeviceOnDesk

    TestCode -- "Request access" --> Controller
    Controller -- "Assign lease" --> TestCode
    Controller -- "Connect to" --> RemoteExporters
    RemoteExporters --> LabDevices
```

This architecture supports developers working with both local systems and
shared lab resources:

1. Developers write code and test code in their IDE
2. For quick tests, they use the test code to access a system on their desk
3. For more complex tests, they connect to remote lab systems through the
   controller
4. The same test code works in both environments

### Cloud Native Developer Workflow

```{mermaid}
:config: {"theme":"base","themeVariables":{"primaryColor":"#f8f8f8","primaryTextColor":"#000","primaryBorderColor":"#e5e5e5","lineColor":"#3d94ff","secondaryColor":"#f8f8f8","tertiaryColor":"#fff"}}
flowchart TB
    subgraph "Web Browser"
        Dev["Developer"]
    end
    
    subgraph "Kubernetes Cluster"
        subgraph "Eclipse Che"
            Workspace["Developer Workspace"]
            TestCode["Test Code"]
            PortFwd["Port Forwarding"]
        end
        
        Controller["Controller"]
    end
    
      subgraph "Local Environment"
          LocalExporter["Local Exporter"]
          DeviceOnDesk["Device Under Test"]
      end
      
      subgraph "Lab"
          RemoteExporters["Exporter"]
          LabDevices["Device Under Test"]
      end
    
    Dev -- "Access via browser" --> Workspace
    Workspace -- "Contains" --> TestCode
    
    TestCode -- "Local system access" --> PortFwd
    PortFwd -- "Forward connection" --> LocalExporter
    LocalExporter -- "Control" --> DeviceOnDesk
    
    TestCode -- "Request access" --> Controller
    Controller -- "Assign lease" --> TestCode
    Controller -- "Connect to" --> RemoteExporters
    RemoteExporters -- "Control" --> LabDevices
```

This architecture provides a modern cloud-native development experience while maintaining flexibility to work with both local and remote systems:

1. Developers access a containerized development environment through a web browser using Eclipse Che
2. The development workspace contains all necessary tools, dependencies, and test code
3. For quick iterations with locally connected systems:
   - Port forwarding enables the cloud workspace to communicate with systems connected to the developer's machine
   - The local Jumpstarter exporter manages the device directly
4. For access to shared lab resources:
   - The same test code can request access to remote devices through the controller
   - The controller manages leases and routes connections through the standard infrastructure

Key benefits of this approach:

- **Consistent Development Environment**: Standardized, reproducible workspaces for all team members
- **Flexibility**: Seamless transition between local and remote system testing
- **Collaboration**: Web-based IDE enables real-time collaboration and knowledge sharing
- **Scalability**: Easy onboarding of new team members with zero local configuration
- **System Flexibility**: Enables a hybrid approach where developers can test locally first, then validate on shared lab systems

This workflow eliminates the distinction between local and cloud development while providing the best of both worlds for system testing.

## Integration with Testing Frameworks

### pytest Integration

Jumpstarter integrates seamlessly with pytest through the `jumpstarter-testing`
package:

```python
from jumpstarter_testing.pytest import JumpstarterTest

class TestMyDevice(JumpstarterTest):
    # Optional: specify which exporter to use based on labels
    exporter_selector = "vendor=acme,model=widget-v2"

    def test_power_cycle(self):
        # Access the device driver through the provided client
        self.client.power.on()
        assert self.client.serial.read_until("boot complete") is not None
        self.client.power.off()
```

### Robot Framework Integration

For teams using Robot Framework, Jumpstarter drivers can be exposed as keywords:

```robotframework
*** Settings ***
Library    JumpstarterLibrary

*** Test Cases ***
Device Boot Test
    Connect To Exporter    selector=vendor=acme,model=widget-v2
    Power On
    ${output}=    Read Serial Until    boot complete
    Should Not Be Empty    ${output}
    Power Off
```
## Best Practices

### Labeling Strategy

Develop a consistent labeling strategy for your exporters to make device
selection straightforward:

- **System Properties**: `arch=arm64`, `cpu=cortex-a53`
- **Organization**: `team=platform`, `project=widget`
- **Capabilities**: `has-video=true`, `has-can=true`
- **Environment**: `env=dev`, `env=production`

### Resource Management

Implement practices to ensure efficient use of shared systems:

- Set appropriate lease timeouts to prevent orphaned resources
- Use CI systems' concurrency controls to manage test parallelism
- Implement monitoring and alerting for device availability
- Create "pools" of identical devices to improve scalability

### Security Considerations

When deploying Jumpstarter in a multi-user environment:

- Use role-based access control to limit which users can access which devices
- Restrict driver access to prevent untrusted code execution
- Isolate the Jumpstarter network from production systems
- Rotate JWT tokens regularly for enhanced security