# Where to Find the Client-Side Code for Managing Connection States in Amnezia VPN

> Locate Amnezia VPN client-side code for connection states. Find vital logic in connectionController.cpp and vpnConnection.cpp for seamless connection management.

- Repository: [Amnezia VPN/amnezia-client](https://github.com/amnezia-vpn/amnezia-client)
- Tags: how-to-guide
- Published: 2026-07-29

---

**The client-side code for managing connection states in the Amnezia VPN client is located primarily in [`client/core/controllers/connectionController.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/controllers/connectionController.cpp) for high-level state orchestration and [`client/vpnConnection.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.cpp) for low-level protocol implementation.**

The Amnezia VPN client relies on a two-layer architecture to manage VPN connection states, bridging the Qt-based UI with native protocol implementations. Understanding this architecture is essential for developers contributing to the amnezia-vpn/amnezia-client repository or troubleshooting connection issues. This guide maps the specific source files and function calls that handle state transitions, from UI requests to wire-level protocol changes.

## High-Level State Orchestration in ConnectionController

The **ConnectionController** class serves as the primary interface between the UI and the VPN engine. Located in [`client/core/controllers/connectionController.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/controllers/connectionController.h) and [`client/core/controllers/connectionController.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/controllers/connectionController.cpp), this controller exposes Qt-friendly signals including `openConnectionRequested`, `closeConnectionRequested`, and `connectionStateChanged`.

This layer performs platform validation to determine if a connection is allowed before delegating work to the low-level engine. It maintains a clean abstraction so that UI code never directly manipulates protocol objects.

## Low-Level Protocol Handling in VpnConnection

The **VpnConnection** class implements the actual VPN protocols and tracks the definitive connection state. Found in [`client/vpnConnection.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.h) and [`client/vpnConnection.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.cpp), this layer maintains the `m_connectionState` member of type `Vpn::ConnectionState` and emits `connectionStateChanged` signals whenever the underlying protocol reports a transition.

Beyond state tracking, `VpnConnection` handles routing updates, kill-switch configuration, and DNS flushing when states change. It communicates with platform-specific backends via `IpcClient` on desktop or native controllers on iOS/macOS.

## How the Architecture Propagates State Changes

### Signal Flow from Engine to UI

During construction, `ConnectionController` subscribes to engine signals to propagate state changes upward:

```cpp
connect(m_vpnConnection, &VpnConnection::connectionStateChanged,
        this, &ConnectionController::connectionStateChanged);

```

This connection ensures that any state change reported by the VPN engine is instantly broadcast to the UI layer through the controller's `connectionStateChanged` signal.

### Querying Connection Status

The controller provides a convenience method for checking the current state without exposing internal engine details:

```cpp
bool ConnectionController::isConnected() const {
    return m_vpnConnection &&
           m_vpnConnection->connectionState() == Vpn::ConnectionState::Connected;
}

```

UI components throughout the application use this `isConnected()` helper to determine interface states.

### Handling Connection Requests

State transitions originate from UI actions bound to the controller's slots:

- **Open connection**: `openConnectionRequested` triggers `VpnConnection::connectToVpn`
- **Close connection**: `closeConnectionRequested` triggers `VpnConnection::disconnectFromVpn`
- **Kill-switch toggle**: `killSwitchModeChangedRequested` forwards to `VpnConnection::onKillSwitchModeChanged`

These connections typically use `Qt::QueuedConnection` to prevent blocking the UI thread during network operations.

## Inside the VpnConnection State Machine

When the underlying protocol reports a change, `VpnConnection::onConnectionStateChanged` executes platform-specific cleanup and setup operations. This includes flushing the DNS cache, configuring split-tunneling rules, and updating the kill-switch status.

Concrete protocol implementations inherit from the abstract base defined in [`client/core/protocols/vpnProtocol.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/protocols/vpnProtocol.h). Specific implementations include:

- **OpenVPN**: [`client/core/protocols/openVpnProtocol.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/protocols/openVpnProtocol.cpp)
- **WireGuard**: [`client/core/protocols/wireGuardProtocol.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/protocols/wireGuardProtocol.cpp)

These protocol objects report their status back to `VpnConnection`, which then updates the canonical `m_connectionState` and emits the change notification.

### Practical Example: Opening a Connection

To initiate a VPN connection from the UI layer:

```cpp
QString serverId = "my-server-id";
DockerContainer container = DockerContainer::WireGuard;
QJsonObject config = {/* … VPN config generated by the configurators … */};

emit connectionController->openConnectionRequested(serverId, container, config);

```

### Practical Example: Reacting to State Changes in QML

```cpp
connect(connectionController, &ConnectionController::connectionStateChanged,
        this, [&](Vpn::ConnectionState state) {
    if (state == Vpn::ConnectionState::Connected) {
        statusLabel->setText("Connected");
    } else if (state == Vpn::ConnectionState::Disconnected) {
        statusLabel->setText("Disconnected");
    }
});

```

### Practical Example: Querying Current Status

```cpp
bool connected = connectionController->isConnected();
qDebug() << "VPN is currently" << (connected ? "online" : "offline");

```

## Summary

- **ConnectionController** ([`client/core/controllers/connectionController.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/controllers/connectionController.cpp)) provides the high-level Qt API for connection state management and platform validation.
- **VpnConnection** ([`client/vpnConnection.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.cpp)) implements the low-level protocol logic, maintains the canonical `Vpn::ConnectionState`, and handles network routing.
- Communication between layers occurs through Qt signals and slots, with `connectionStateChanged` propagating updates from the engine to the UI.
- Protocol-specific implementations in `client/core/protocols/` inherit from [`vpnProtocol.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/vpnProtocol.h) and report status to `VpnConnection`.
- The `isConnected()` convenience method offers a simple boolean check for UI components.

## Frequently Asked Questions

### Where is the connection state enum defined in the Amnezia VPN client?

The `Vpn::ConnectionState` enum is defined in the `VpnConnection` header file within [`client/vpnConnection.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.h). This enum represents all possible states including `Connected`, `Disconnected`, and intermediate states during connection establishment.

### How does the UI receive real-time connection state updates?

The UI receives updates through Qt's signal-slot mechanism. The `ConnectionController` emits `connectionStateChanged(Vpn::ConnectionState)` whenever the underlying `VpnConnection` reports a state change, allowing QML and QWidget interfaces to react immediately without polling.

### What handles the kill-switch when the connection state changes?

The `VpnConnection` class manages kill-switch updates within its `onConnectionStateChanged` handler. When the state transitions, it invokes platform-specific logic via `IpcClient` on desktop or native controllers on mobile platforms to ensure the kill-switch rules align with the current connection status.

### Why are there separate layers for connection control and VPN implementation?

The separation allows the **ConnectionController** to focus on UI coordination and platform policy checks while **VpnConnection** handles the complexity of protocol-specific implementations. This architecture isolates protocol differences (OpenVPN vs. WireGuard) from the user interface, enabling both layers to be tested and maintained independently.