add docs

doc/flow_diagrams.md

@@ -0,0 +1,75 @@
+# 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]
+```