Skip to main content

​
Overview

FreeTAKServer (FTS) uses a Model-View-Controller (MVC) pattern with a Model-Driven Architecture (MDA) approach. The architecture is built on the DigitalPy framework and follows enterprise design patterns for modularity, scalability, and maintainability.

​
Architectural Layers

​
MVC Pattern

FTS implements a clear separation of concerns:
  • Domain Model: CoT (Cursor on Target) objects generated from UML models
  • Protocol Objects: Base class FTSProtocolObject for all domain entities
  • Core Domain: Event, Point, Detail and other fundamental CoT components
  • Location: FreeTAKServer/model/ and FreeTAKServer/components/core/domain/
  • Service Controllers: Handle business logic for each service (TCP CoT, SSL CoT, REST API)
  • CoT Controllers: Process specific CoT types (presence, chat, emergency)
  • Serialization Controllers: XML/JSON serialization and deserialization
  • Location: FreeTAKServer/controllers/ and service-specific controllers
  • REST API Views: Flask-based endpoints for web interface
  • WebSocket Handlers: Real-time communication via SocketIO
  • Response Formatters: XML and JSON output formatting
  • Location: FreeTAKServer/services/rest_api_service/views/

​
Core Architecture Components

​
DigitalPy Framework Integration

FTS is built on top of DigitalPy, which provides: 
# FreeTAKServer/controllers/services/FTS.py
class FTS(DigitalPy):
    def __init__(self):
        super().__init__()
        # Service initialization
        self.SSLCoTService = None
        self.CoTService = None
        self.TCPDataPackageService = None
        # ... other services
Key Features:
  • Service Management: Dynamic service registration and lifecycle management
  • Action Mapper: Routes requests to appropriate controllers
  • Object Factory: Dependency injection and object creation
  • Component System: Modular component architecture

​
Domain Model Architecture

​
CoT Node System

All CoT objects inherit from CoTNode, which provides tree-based data structure: 
# FreeTAKServer/components/core/abstract_component/cot_node.py:8-15
class CoTNode(Node, FTSProtocolObject):
    def __init__(self, node_type, configuration, model, oid=None):
        # Dictionary containing CoT attributes
        self.cot_attributes = {}
        # XML representation of the CoT
        self.xml: etree.ElementTree = etree.Element(self.__class__.__name__)
        self.text = ""
        super().__init__(node_type, configuration, model, oid)
Key Characteristics:
  • Parent-child relationship management
  • XML serialization support
  • Property-based attribute access via @CoTProperty decorator
  • Support for nested CoT structures

​
Event Model

The Event class is the root CoT object: 
# FreeTAKServer/components/core/domain/domain/_event.py:16-44
class Event(CoTNode):
    def __init__(self, configuration: Configuration, model, oid=None):
        super().__init__(self.__class__.__name__, configuration, model, oid)
        
        self.cot_attributes["version"] = None  # Schema version (e.g., 2.0)
        self.cot_attributes["uid"] = None      # Globally unique identifier
        self.cot_attributes["type"] = None     # Hierarchical event type
        self.cot_attributes["how"] = None      # Coordinate generation method
        self.cot_attributes["stale"] = None    # Expiration timestamp
        self.cot_attributes["start"] = None    # Start validity timestamp
        self.cot_attributes["time"] = None     # Event generation timestamp
Event Structure:
  • Attributes: version, uid, type, how, time, start, stale
  • Children: point (location), detail (additional data)
  • Properties: Exposed via @CoTProperty decorator with getters/setters

​
Request-Response Pattern

FTS uses an action-based request-response pattern: Implementation Example: 
# Request creation
request = ObjectFactory.get_new_instance("request")
request.set_action("XMLToDict")
request.set_value("message", xml_string)

# Action mapping
actionmapper = ObjectFactory.get_instance("syncactionMapper")
response = ObjectFactory.get_new_instance("response")
actionmapper.process_action(request, response)

# Response retrieval
result = response.get_value("dict")

​
Service Architecture

​
Service Lifecycle

Each service extends DigitalPyService: 
# FreeTAKServer/services/tcp_cot_service/tcp_cot_service_main.py:73-97
class TCPCoTServiceMain(DigitalPyService):
    def __init__(
        self,
        service_id,
        subject_address,
        subject_port,
        subject_protocol,
        integration_manager_address,
        integration_manager_port,
        integration_manager_protocol,
        formatter: Formatter,
    ):
        super().__init__(
            service_id,
            subject_address,
            subject_port,
            subject_protocol,
            integration_manager_address,
            integration_manager_port,
            integration_manager_protocol,
            formatter
        )
Service Responsibilities:
  1. Connection Management: Accept and manage client connections
  2. Message Processing: Parse, validate, and route CoT messages
  3. Event Distribution: Broadcast messages to connected clients
  4. State Management: Track active clients and sessions

​
Multi-Threading Architecture

FTS uses thread pools for concurrent client handling: 
# Thread pool for client connections
from multiprocessing.pool import ThreadPool

# Separate threads for:
# - Accepting new connections
# - Receiving data from clients
# - Sending data to clients
# - Processing CoT messages

​
Data Flow

​
CoT Message Processing Pipeline

​
XML to Domain Object Conversion

# FreeTAKServer/core/parsers/XMLCoTController.py:64-75
# Serialize XML to etree
event = etree.fromstring(data.xmlString)

# Convert XML to dictionary
request.set_action("XMLToDict")
request.set_value("message", data.xmlString)
actionmapper.process_action(request, response)
data_dict = response.get_value("dict")

# Convert machine-readable type to human-readable
request.set_action("ConvertMachineReadableToHumanReadable")
request.set_value("machine_readable_type", data_dict["event"]["@type"])
actionmapper.process_action(request, response)

​
Persistence Layer

​
Database Architecture

  • ORM: SQLAlchemy for database abstraction
  • Database Controller: FreeTAKServer/core/persistence/DatabaseController.py
  • Models: SQLAlchemy models in FreeTAKServer/model/SQLAlchemy/
Persisted Data:
  • User authentication and sessions
  • CoT event history
  • Mission data and packages
  • Video stream metadata
  • Client connection information

​
Configuration Management

​
Main Configuration

# Singleton configuration object
from FreeTAKServer.core.configuration.MainConfig import MainConfig
config = MainConfig.instance()
Configuration Sources:
  • INI Files: Primary configuration via config.ini
  • Environment Variables: Override configuration values
  • Command Line Arguments: Runtime configuration
  • Component Configs: Component-specific settings

​
Telemetry and Monitoring

​
OpenTelemetry Integration

from opentelemetry.trace import Status, StatusCode
from digitalpy.core.telemetry.tracer import Tracer

# Tracing support throughout the codebase
# for performance monitoring and debugging

​
Logging Architecture

from FreeTAKServer.core.configuration.CreateLoggerController import CreateLoggerController
from FreeTAKServer.core.configuration.LoggingConstants import LoggingConstants

loggingConstants = LoggingConstants(log_name="ServiceName")
logger = CreateLoggerController("ServiceName", logging_constants=loggingConstants).getLogger()

​
Security Architecture

​
SSL/TLS Support

  • Certificate Generation: AtakOfTheCerts utility for certificate management
  • SSL Services: Separate SSL CoT and HTTPS TAK API services
  • Client Authentication: Certificate-based client authentication

​
Authentication and Authorization

  • Flask-Login: Session management for REST API
  • API Keys: Token-based authentication support
  • Certificate Auth: x.509 certificate validation

​
Extensibility

The architecture supports extension through:
  1. Component System: Add new components in components/extended/
  2. Service Plugins: Create new services implementing DigitalPyService
  3. CoT Handlers: Register handlers for specific CoT types
  4. Action Mappers: Add new actions to the request-response system

​
Design Patterns

​
Patterns Used

  • MVC: Model-View-Controller separation
  • Factory: Object creation via ObjectFactory
  • Singleton: Configuration and service instances
  • Strategy: Multiple serialization strategies (XML, JSON, Protobuf)
  • Observer: Event-based message distribution
  • Command: Action-based request handling
  • Repository: Database access abstraction

​
Performance Considerations

​
Optimization Strategies

  1. Connection Pooling: Reuse database connections
  2. Thread Pools: Limit thread creation overhead
  3. Caching: Type mapping and configuration caching
  4. Lazy Loading: Load domain objects on demand
  5. Asynchronous I/O: EventLet for concurrent operations

Services

Learn about FTS service architecture

Components

Explore the component system

CoT Messages

Understand CoT message format

Installation

Get started with FTS

Build docs developers (and LLMs) love

Get started for freeTalk to us