update test arena

doc/architecture.md

@@ -0,0 +1,36 @@
+# TestArena Architecture Documentation
+
+## Overview
+TestArena is a web-based test management and execution platform designed to orchestrate test scenarios across different environments. It consists of a Flask-based frontend/backend that communicates with a remote execution server.
+
+## System Components
+
+### 1. Web Application (Flask)
+- **Frontend**: Built with HTML, CSS (Vanilla), and JavaScript. Provides a dashboard for monitoring jobs, submitting new tests, and viewing logs.
+- **Backend**: Flask server handling authentication, job management, and API requests.
+- **Database**: SQLite (default) or PostgreSQL, managed via SQLAlchemy. Stores users and job history.
+
+### 2. Remote Execution Server
+- Handles the actual execution of test scenarios.
+- Exposes APIs for queueing, status polling, and aborting/deleting jobs.
+- Provides access to execution logs and results.
+
+## Key Workflows
+
+### Job Submission
+1. User selects a branch and validates it via SSH on the remote server.
+2. User selects test scenarios to run.
+3. User reviews and submits the job.
+4. The web app creates a local `Job` record and sends a POST request to the remote `/api/queue` endpoint.
+
+### Status Polling
+1. A background thread in the Flask app polls the remote server every 20 seconds for all `waiting` or `in_progress` jobs.
+2. The dashboard also polls the local API every 5 seconds when a job is being viewed to provide real-time updates.
+
+### Job Abort/Delete
+- Users can abort running jobs or delete them entirely. These actions are synchronized with the remote server.
+
+## Technology Stack
+- **Backend**: Python, Flask, Flask-SQLAlchemy, Flask-Login, Requests.
+- **Frontend**: HTML5, CSS3, JavaScript (ES6).
+- **Remote Communication**: REST API, SSH (for branch validation and scenario scanning).