# Architecture & Design

This document describes the high-level architecture and design of the TestArena Backend.

## System Architecture

TestArena follows a decoupled architecture consisting of a RESTful API and a background worker.

```mermaid
graph TD
    User((User)) -->|HTTP| API[FastAPI Web Server]
    API -->|Read/Write| DB[(SQLite Database)]
    API -->|Create| FS[Filesystem /testarena]
    Worker[Background Worker] -->|Poll| DB
    Worker -->|Execute| Scripts[Execution Scripts]
    Scripts -->|Build/Test| QEMU[QEMU Emulator]
    Scripts -->|Write Logs| FS
    User -->|View| Dashboard[Web Dashboard]
    Dashboard -->|API Calls| API
```

## Core Components

### 1. FastAPI Web Server (`main.py`)
The entry point for the system. It handles:
*   Receiving test queue requests via REST API.
*   Managing the SQLite database.
*   Serving the web dashboard and static files.
*   Providing endpoints for status monitoring, aborting, and deleting queues.

### 2. Background Worker (`worker.py`)
A dedicated process that continuously polls the database for "Waiting" queues. Its responsibilities include:
*   Cloning and checking out the correct branch of the target repository.
*   Orchestrating the build process using `idf.py build`.
*   Running the QEMU simulation.
*   Executing individual test scenarios.
*   Managing real-time logging to the filesystem.

### 3. Execution Scripts (`TPF/`)
A set of specialized scripts for different stages of the workflow:
*   `gitea_repo_controller.sh`: Handles Git operations (clone, checkout, pull).
*   `scenario_execution.py`: Parses XML scenarios and runs test suites.
*   `test_execution.sh`: Executes individual test commands and generates HTML logs.
*   `scenario_exe_parser.py`: Helper script for parsing XML scenario files.

## Technology Stack

| Layer | Technology |
| :--- | :--- |
| **Backend Framework** | FastAPI (Python 3.12+) |
| **Database** | SQLite with SQLAlchemy ORM |
| **Frontend** | Vanilla HTML5, CSS3 (Modern Glassmorphism UI), JavaScript |
| **Process Management** | Systemd (testarena-app, testarena-worker) |
| **Web Server / Proxy** | Nginx |
| **Build System** | ESP-IDF (Espressif IoT Development Framework) |
| **Emulator** | QEMU (XTENSA) |
| **Scripting** | Bash, Python |

## Design Principles

*   **Decoupling**: The API and Worker are separate processes, allowing the UI to remain responsive even during heavy test execution.
*   **Real-time Visibility**: All subprocess output is streamed in real-time to both the console and log files.
*   **Robustness**: Implemented global timeouts, automatic cleanup of orphaned processes, and detailed error handling.
*   **Automation**: The entire deployment and execution flow is fully automated to minimize manual intervention.