Server Technicals
=================

.. toctree::
   :titlesonly:
   :maxdepth: 1

   Authentication Server <de-server-technicals-authenticator>
   Authentication Server Internals <de-server-technicals-authentication>
   Communication Server Internals <de-server-technicals-communication>
   Authentication ↔ Communication Flow <de-server-technicals-auth-comm-flow>
   Mesh Communication Server Relay <de-server-technicals-mesh-relay>
   API Endpoints <de-server-api-endpoints>
   Authentication Flow <de-server-authentication-flow>
   Configuration <de-server-configuration>
   Database Schema <de-server-database-schema>
   Message Propagation <de-server-message-propagation>
   S2S Authentication <de-server-s2s-authentication>

Overview
--------

The DroneEngage server architecture consists of two main backend components:

- **Authentication Server** (\ ``droneegnage_authenticator``\ ) - Validates drone units and web clients against predefined accounts, and returns connection details for the assigned communication server.
- **Communication Server** (\ ``droneengage_server``\ ) - Exchanges communication messages between different units and web clients via WebSocket connections.

These two servers work together to provide secure, scalable communication for the DroneEngage ecosystem.

Architecture
------------

Authentication Server
~~~~~~~~~~~~~~~~~~~~~

- Validates login credentials (account name, access code)
- Supports multiple account storage backends (single account, JSON file, MySQL database)
- Selects an appropriate communication server for each authenticated client
- Maintains a persistent WebSocket connection to communication servers for coordination
- Returns connection details (host, port, temporary login key) to clients

Communication Server
~~~~~~~~~~~~~~~~~~~~

- Maintains WebSocket connections to authenticated drone units and web clients
- Routes messages between parties based on account and group membership
- Maintains a persistent WebSocket connection to the authentication server
- Generates temporary login keys for new client connections
- Manages account rooms and active sender lists

Communication Flow
------------------

1. **Server Startup**: Communication server connects to authentication server via WebSocket and sends server info
2. **Client Authentication**: Client sends HTTP POST to authentication server with credentials
3. **Server Selection**: Authentication server validates credentials and selects a communication server
4. **Login Reservation**: Authentication server requests communication server to generate a temporary login key
5. **Key Generation**: Communication server generates a temporary login key and stores it in a waiting list
6. **Key Delivery**: Communication server returns the key and connection details to authentication server
7. **Client Connection**: Client receives connection details and establishes WebSocket to communication server using the temporary key
8. **Connection Acceptance**: Communication server validates the temporary key and accepts the WebSocket connection

Key Concepts
------------

- **No HTTP Redirects**: The authenticator does not redirect clients. It returns JSON with connection details.
- **Temporary Login Keys**: Single-use keys generated by the communication server, valid for a limited time.
- **Server-to-Server WebSocket**: Persistent connection between authentication and communication servers for coordination.
- **Account Rooms**: Communication server groups clients by account ID for message routing.
- **Actor Types**: Clients are classified as GCS (Ground Control Station) or Agent (drone unit).

Related Documentation
---------------------

- :doc:`Authentication Server Internals <de-server-technicals-authentication>`
- :doc:`Communication Server Internals <de-server-technicals-communication>`
- :doc:`Authentication ↔ Communication Flow <de-server-technicals-auth-comm-flow>`