====== Software Architecture ======

TeamCAMS is built around a distributed **client-server architecture** designed to support both laboratory-based and remote experimental studies. Running experiments depends on three main components: the **Manager**, the **communication layer**, and the browser-based **Operator Interfaces**.

### Manager Application

The core of the platform is the **Manager**, a desktop application developed primarily in **C++** using the **Qt framework**, with some components implemented in **JavaScript** to support scripting and scenario customization. Acting as the central execution engine of TeamCAMS, the Manager is responsible for:

- Executing and maintaining the simulation state.
- Managing experimental scenarios and study workflows.
- Synchronizing all connected participants.
- Collecting and storing experimental data.
- Monitoring participant activity in real time.
- Providing researchers with administrative and analysis tools.

As the authoritative source of information, the Manager ensures that all participants share a consistent view of the simulation environment.

From an architectural perspective, the Manager functions as an **on-premises server** running directly on the researcher's computer. Unlike cloud-based solutions, the simulation logic, experimental configuration, and collected data remain under the direct control of the researcher. This approach simplifies compliance with institutional data management policies while providing full ownership of both the experimental environment and the generated datasets.

A single Manager instance can host and supervise **multiple concurrent sessions**, allowing researchers to run several experimental trials simultaneously. Each session may involve one or more operators, enabling the efficient management of large-scale studies involving multiple teams or participant groups. The Manager continuously coordinates the connected clients, maintains session states, and records all interactions for subsequent analysis.

The only operational requirement is that the Manager application remains running on the researcher's computer for the duration of the experiment. As long as the Manager is active and connected to the MQTT communication infrastructure, participants can access their assigned sessions remotely through a web browser and interact with the simulation in real time.

To facilitate deployment across common research environments, the Manager is currently distributed for **Windows** and **Linux** operating systems on **AMD64 (x86-64)** architectures. This ensures compatibility with the majority of modern desktop and server hardware available in academic and industrial research settings.
### Secure MQTT Communication Layer

Communication between the Manager and the distributed Operator Interfaces is handled through an **encrypted MQTT messaging layer**. MQTT was selected because of its lightweight design, low latency, and suitability for real-time distributed applications.

The MQTT layer acts exclusively as a communication infrastructure, enabling the exchange of commands, status updates, participant actions, and simulation events between the Manager and connected clients. Importantly, the simulation itself remains hosted and controlled by the researcher's computer, while MQTT serves only as a secure transport mechanism.

At present, TeamCAMS uses a publicly available MQTT broker service by default. An **MQTT broker** can be viewed as a message hub that receives messages from one system component and delivers them to the appropriate recipients. In TeamCAMS, the broker facilitates communication between the Manager and all connected Operator Interfaces, allowing participants and researchers to exchange information in real time without requiring direct connections between individual devices.

The default broker simplifies deployment and enables researchers to quickly set up and run experiments without additional infrastructure. However, TeamCAMS is completely broker-independent and can be configured to work with any MQTT broker. Researchers may choose to use a self-hosted broker, an institutional server, or a commercial cloud-based solution depending on their requirements for security, performance, scalability, and data governance.

All communications are protected through encryption, ensuring that participant interactions and experimental data remain confidential and accessible only to authorized researchers.


### Browser-Based Operator Interfaces

Participants interact with TeamCAMS through a web-based **Operator Interface** implemented using modern web technologies. Because the interface runs directly within a standard web browser, no dedicated software installation is required.

This approach offers several advantages:

- Access from desktops, laptops, and tablets.
- Simplified deployment and maintenance.
- Cross-platform compatibility.
- Support for both local and geographically distributed participants.
- Easy integration into laboratory and remote research settings.

Each operator connects through the MQTT communication layer and receives real-time updates from the Manager while transmitting actions and responses back to the simulation.

### Remote Collaboration

The combination of a centralized Manager, secure MQTT messaging, and browser-based clients allows TeamCAMS to support collaborative experiments involving multiple participants connected from different locations. Researchers can supervise sessions remotely, control experimental conditions, and collect synchronized data from all participants in real time.

This architecture provides the flexibility required for modern human-AI interaction research, enabling scalable experiments while preserving security, reproducibility, and researcher control over both the simulation environment and the generated data.