# ASF TestArena - Architecture

## System Overview

```
┌─────────────────────────────────────────────────────────────┐
│                         Internet                            │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTPS (443)
                         │ testarena.nabd-co.com
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                    Caddy Reverse Proxy                      │
│  • SSL/TLS Termination                                      │
│  • Automatic HTTPS (Let's Encrypt)                          │
│  • Load Balancing                                           │
│  • Security Headers                                         │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP (5000)
                         │ Internal Docker Network
                         ↓
┌─────────────────────────────────────────────────────────────┐
│              Flask Web Application (Gunicorn)               │
│  Container: testarena_web                                   │
│  • Authentication (Flask-Login)                             │
│  • User Management                                          │
│  • Job Submission                                           │
│  • Dashboard                                                │
│  • API Endpoints                                            │
└────────────────────────┬────────────────────────────────────┘
                         │ PostgreSQL (5432)
                         │ Internal Network Only
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                PostgreSQL Database                          │
│  Container: testarena_db                                    │
│  • User accounts                                            │
│  • Job records                                              │
│  • Persistent storage                                       │
└─────────────────────────────────────────────────────────────┘
```

## Application Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Flask Application                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   Routes     │  │   Models     │  │  Templates   │    │
│  │              │  │              │  │              │    │
│  │ • auth.py    │  │ • User       │  │ • login.html │    │
│  │ • admin.py   │  │ • Job        │  │ • dashboard  │    │
│  │ • dashboard  │  │              │  │ • admin      │    │
│  │ • jobs.py    │  │              │  │ • jobs       │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         │                 │                 │             │
│         └─────────────────┼─────────────────┘             │
│                           │                               │
│  ┌────────────────────────┴────────────────────────┐     │
│  │           SQLAlchemy ORM                        │     │
│  └────────────────────────┬────────────────────────┘     │
│                           │                               │
└───────────────────────────┼───────────────────────────────┘
                            │
                            ↓
                    PostgreSQL Database
```

## User Flow Diagrams

### Admin Workflow

```
┌─────────┐
│  Login  │
└────┬────┘
     │
     ↓
┌─────────────────┐
│  Admin Check    │
└────┬────────────┘
     │
     ├─→ Admin Dashboard
     │   ├─→ Create User
     │   ├─→ Reset Password
     │   ├─→ Delete User
     │   └─→ View All Jobs
     │
     └─→ User Dashboard
         ├─→ View Own Jobs
         └─→ Submit Jobs
```

### User Workflow

```
┌─────────┐
│  Login  │
└────┬────┘
     │
     ↓
┌──────────────┐
│  Dashboard   │
└────┬─────────┘
     │
     ├─→ View Jobs
     │   ├─→ Click Job
     │   ├─→ View Details
     │   └─→ Abort Job (if in progress)
     │
     └─→ Submit New Job
         ├─→ Step 1: Branch Name
         ├─→ Step 2: Select Scenarios
         ├─→ Step 3: Choose Environment
         ├─→ Step 4: Test Mode + Options
         └─→ Step 5: Submit
```

## Job Submission Flow

```
┌──────────────────┐
│ User clicks      │
│ "Submit Job"     │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Step 1:          │
│ Enter Branch     │
│ Name             │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Backend:         │
│ • Checkout branch│
│ • Run scanner    │
│ • Get scenarios  │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Step 2:          │
│ Select Scenarios │
│ (Checkboxes)     │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Step 3:          │
│ Choose Env       │
│ • Sensor Hub     │
│ • Main Board     │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Step 4:          │
│ Test Mode        │
│ • Simulator      │
│ • HIL            │
│ + Options        │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Create Job       │
│ Record in DB     │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Start Test       │
│ (Background)     │
└────────┬─────────┘
         │
         ↓
┌──────────────────┐
│ Update Status    │
│ • In Progress    │
│ • Passed         │
│ • Failed         │
│ • Aborted        │
└──────────────────┘
```

## Database Schema

```
┌─────────────────────────────────────────┐
│              Users Table                │
├─────────────────────────────────────────┤
│ id (PK)              INTEGER            │
│ username             VARCHAR(80) UNIQUE │
│ password_hash        VARCHAR(255)       │
│ is_admin             BOOLEAN            │
│ created_at           TIMESTAMP          │
└─────────────────┬───────────────────────┘
                  │
                  │ 1:N
                  │
┌─────────────────┴───────────────────────┐
│              Jobs Table                 │
├─────────────────────────────────────────┤
│ id (PK)              INTEGER            │
│ user_id (FK)         INTEGER            │
│ branch_name          VARCHAR(255)       │
│ scenarios            TEXT (JSON)        │
│ environment          VARCHAR(50)        │
│ test_mode            VARCHAR(50)        │
│ status               VARCHAR(20)        │
│ submitted_at         TIMESTAMP          │
│ completed_at         TIMESTAMP          │
│ duration             INTEGER            │
│ keep_devbenches      BOOLEAN            │
│ reuse_results        BOOLEAN            │
│ results_path         VARCHAR(500)       │
└─────────────────────────────────────────┘
```

## Network Architecture

```
┌─────────────────────────────────────────────────────────┐
│                  Docker Host                            │
│                                                         │
│  ┌───────────────────────────────────────────────────┐ │
│  │         Caddy Network (External)                  │ │
│  │                                                   │ │
│  │  ┌──────────────┐      ┌──────────────┐         │ │
│  │  │    Caddy     │──────│ testarena_web│         │ │
│  │  │  Container   │      │  Container   │         │ │
│  │  └──────────────┘      └──────┬───────┘         │ │
│  │                               │                  │ │
│  └───────────────────────────────┼──────────────────┘ │
│                                  │                    │
│  ┌───────────────────────────────┼──────────────────┐ │
│  │      TestArena Network        │                  │ │
│  │                               │                  │ │
│  │  ┌──────────────┐      ┌──────┴───────┐         │ │
│  │  │ testarena_web│──────│ testarena_db │         │ │
│  │  │  Container   │      │  Container   │         │ │
│  │  └──────────────┘      └──────────────┘         │ │
│  │                                                  │ │
│  └──────────────────────────────────────────────────┘ │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │              Docker Volumes                      │  │
│  │  • postgres_data (Database persistence)          │  │
│  │  • test_results (Test output files)              │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

## Security Layers

```
┌─────────────────────────────────────────────────────────┐
│ Layer 1: Network Security                              │
│ • Firewall rules                                       │
│ • Only Caddy exposes ports to internet                 │
│ • Internal Docker networks isolated                    │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│ Layer 2: Transport Security                            │
│ • HTTPS/TLS via Caddy                                  │
│ • Automatic certificate management                     │
│ • Security headers (HSTS, CSP, etc.)                   │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│ Layer 3: Application Security                          │
│ • Flask-Login session management                       │
│ • Password hashing (Werkzeug)                          │
│ • CSRF protection (Flask-WTF)                          │
│ • Role-based access control                            │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│ Layer 4: Database Security                             │
│ • PostgreSQL authentication                            │
│ • Network isolation (internal only)                    │
│ • Encrypted connections                                │
│ • Regular backups                                      │
└─────────────────────────────────────────────────────────┘
```

## File System Layout

```
/app (Container)
├── routes/
│   ├── auth.py          # Login/logout endpoints
│   ├── admin.py         # User management endpoints
│   ├── dashboard.py     # Dashboard endpoints
│   └── jobs.py          # Job submission endpoints
├── templates/
│   ├── base.html        # Base template with navbar
│   ├── login.html       # Login page
│   ├── admin/
│   │   └── dashboard.html
│   ├── dashboard/
│   │   └── index.html
│   └── jobs/
│       ├── submit.html
│       ├── submit_step2.html
│       ├── submit_step3.html
│       └── submit_step4.html
├── static/
│   ├── css/
│   │   └── style.css    # Modern theme
│   └── uploads/
│       └── icon.png     # Logo
├── test_results/        # Volume mount
│   └── [job_id]/
│       └── index.html   # Test results
├── models.py            # Database models
└── __init__.py          # App factory

/var/lib/postgresql/data (Volume)
└── [PostgreSQL data files]
```

## Technology Stack Details

```
┌─────────────────────────────────────────────────────────┐
│                    Frontend Layer                       │
│  • HTML5                                                │
│  • CSS3 (Modern gradient design)                        │
│  • Vanilla JavaScript (No frameworks)                   │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│                  Application Layer                      │
│  • Flask 3.0.0 (Web framework)                          │
│  • Flask-Login 0.6.3 (Authentication)                   │
│  • Flask-SQLAlchemy 3.1.1 (ORM)                         │
│  • Flask-WTF 1.2.1 (Forms & CSRF)                       │
│  • Gunicorn 21.2.0 (WSGI server)                        │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│                   Database Layer                        │
│  • PostgreSQL 15 (Relational database)                  │
│  • psycopg2-binary 2.9.9 (Python adapter)               │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│                Infrastructure Layer                     │
│  • Docker (Containerization)                            │
│  • Docker Compose (Orchestration)                       │
│  • Caddy 2.x (Reverse proxy)                            │
└─────────────────────────────────────────────────────────┘
```

## Deployment Pipeline (Future)

```
┌──────────────┐
│ Git Push     │
└──────┬───────┘
       │
       ↓
┌──────────────┐
│ CI/CD        │
│ • Run tests  │
│ • Build image│
└──────┬───────┘
       │
       ↓
┌──────────────┐
│ Docker       │
│ Registry     │
└──────┬───────┘
       │
       ↓
┌──────────────┐
│ Production   │
│ Server       │
│ • Pull image │
│ • Deploy     │
└──────────────┘
```

## Scaling Strategy (Future)

```
                    ┌──────────────┐
                    │ Load Balancer│
                    └──────┬───────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ↓                  ↓                  ↓
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│ Web Instance 1│  │ Web Instance 2│  │ Web Instance 3│
└───────┬───────┘  └───────┬───────┘  └───────┬───────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                           ↓
                  ┌────────────────┐
                  │ PostgreSQL     │
                  │ (Primary)      │
                  └────────┬───────┘
                           │
                           ↓
                  ┌────────────────┐
                  │ PostgreSQL     │
                  │ (Replica)      │
                  └────────────────┘
```

This architecture provides a solid foundation for Phase 1 and is designed to scale for Phase 2 implementation.