# Workflows & Flowcharts

This document provides visual representations of the key processes within the TestArena system.

## 1. Test Queue Submission Flow

This flowchart shows the process from when a user submits a queue until it is ready for the worker.

```mermaid
sequenceDiagram
    participant User
    participant API as FastAPI (main.py)
    participant DB as SQLite
    participant FS as Filesystem

    User->>API: POST /api/queue (Payload)
    API->>API: Extract Queue ID, Source, Tasks
    API->>FS: Create /testarena/<queue_id> folder
    API->>FS: Create queue_status.json
    API->>DB: Insert Queue & Task records
    API-->>User: 200 OK (Queue OK)
```

## 2. Worker Execution Workflow

This diagram illustrates the lifecycle of a test queue as processed by the background worker.

```mermaid
flowchart TD
    Start([Start Worker]) --> Poll{Poll DB for 'Waiting'}
    Poll -- No --> Wait[Wait 5s] --> Poll
    Poll -- Yes --> Running[Set Status to 'Running']
    Running --> Clone[Clone/Checkout Repo]
    Clone --> Build[Build Firmware: idf.py build]
    Build --> QEMU[Start QEMU: idf.py qemu]
    QEMU --> Loop[Loop through Tasks]
    
    subgraph Task Execution
        Loop --> RunScript[Run scenario_execution.py]
        RunScript --> Stream[Stream Output to Log]
        Stream --> Parse[Parse Results]
        Parse --> UpdateDB[Update Task Status & Result]
    end
    
    UpdateDB --> Next{More Tasks?}
    Next -- Yes --> Loop
    Next -- No --> Finish[Set Queue to 'Finished']
    Finish --> Wait
```

## 3. Real-time Logging Architecture

How logs are captured and displayed to the user.

```mermaid
graph LR
    Sub[Subprocess] -->|Stdout/Stderr| Pipe[Pipe]
    Pipe -->|Read Line| Worker[worker.py]
    Worker -->|Write| File[queue_log.txt]
    Worker -->|Print| Console[Systemd Journal]
    User -->|View| Dashboard[Web Dashboard]
    Dashboard -->|Fetch| API[FastAPI]
    API -->|Read| File
```

## 4. Delete Queue Workflow

The process of cleaning up system data.

```mermaid
flowchart LR
    Req[DELETE /api/delete/{id}] --> DB[Delete DB Records]
    DB --> FS[Remove /testarena/{id} Directory]
    FS --> Res[Return Success]
```