Architecture Overview

1. Architecture Overview

This section provides a comprehensive overview of the Service API architecture, including its components, interactions, design principles, and technical decisions that shaped the system.

1.1. System Context

The Service API serves as an integration layer between carrier/service provider systems and the underlying ACS (Auto Configuration Server) systems that manage customer premises equipment (CPE) using TR-069 protocol. It provides both XML/SOAP and REST interfaces for device management, service provisioning, and retrieving device information.

1.1.1. Business Purpose

  • Enables service providers to remotely provision and manage customer devices

  • Provides real-time access to device configurations and status

  • Automates device configuration changes for new service activations

  • Facilitates diagnostics and troubleshooting operations

  • Maintains mapping between customer accounts and device identifiers

1.1.2. API Overview

The API exposes a SOAP web-service interface that links carrier back-office systems with the ACS platform. External applications send synchronous requests to the API and receive standardized responses with success/fail status and appropriate error codes when required.

The API exposes the following core operations:

  • Wireless Management – Configure and retrieve wireless settings

  • Port Configuration – Create, update, delete, and retrieve port mappings

  • Subscription Management – Activate/deactivate service subscriptions

  • Network Mapping – Discover and map connected devices

  • Diagnostics – Run ping tests and speed tests

  • Device Initialization – Set up new devices

  • User Authentication – Verify user credentials and retrieve associated devices

All operations adhere to a uniform response contract with standardized success/fail indicators and appropriate error codes.

1.1.3. System Context Diagram

Diagram

1.2. Component Architecture

The application follows a layered architecture pattern with clear separation of concerns:

1.2.1. Architectural Layers

Diagram

1.2.2. Key Components in Detail

SOAP Endpoint Layer

The SOAP Endpoint layer is the entry point for external clients and is responsible for:

  • Exposing SOAP endpoints for service operations

  • Handling XML/SOAP requests and producing appropriate responses

  • Delegating processing to appropriate service components

  • Error handling and status code mapping

  • Authentication and authorization validation

  • Logging and metrics collection

Service Layer

The service layer contains the core business logic and orchestrates operations:

  • Implements business rules and domain logic

  • Coordinates calls to processors and external systems

  • Applies data transformations between persistence and API models

  • Implements error handling and validation

  • Provides a clean API for the endpoint layer

  • Manages transactions and operation sequences

Processing Layer

The processing layer contains specialized components for different domains:

  • WirelessParameterProcessor: Handles wireless configuration processing

  • PortsProcessor: Manages port mapping operations

  • SpeedTestProcessor: Executes and processes speed test diagnostics

  • FtApiParameterProcessor: Processes TR-069 parameters

Helper Components

Helper components provide utility functions and shared services:

  • FtServiceApiHelper: Core utility functions for API operations

  • FtApiServiceEncryptionHandler: Handles encryption/decryption operations

  • FtApiServiceTransactionHandler: Manages transaction processing

  • FtServiceApiMetricsUtils: Collects and reports metrics

  • FtApiMessageHelper: Handles message formatting and processing

  • SystemLogger: Provides logging capabilities

Integration Layer

The integration layer handles communication with external systems:

  • RestToApiService: Client for ACS REST API

  • Transforms data between internal and external formats

  • Handles protocol-specific details

  • Implements error handling for external system interactions

Repository Layer

The repository layer handles data access:

  • CpeRepository: Manages CPE device data

  • DeviceRepository: Handles device information

  • SpUserRepository: Manages user data

  • Provides data access methods for service components

  • Maps between database entities and domain objects

Configuration Layer

The configuration layer manages application settings:

  • WirelessConfig: Wireless-specific configuration

  • SubscriptionConfig: Subscription service configuration

  • ServiceGroupConfig: Service group settings

  • FTServiceApiConfig: Core API configuration

  • SpeedTestConfig: Speed test diagnostic settings

Exception Handling

The application implements a comprehensive exception hierarchy:

  • FtApiException: Base exception class

  • FtServiceApiException: Service-level exceptions

  • FtApiDataLayerException: Data access exceptions

  • FtApiLogicLayerException: Business logic exceptions

  • Standardized error codes and messages

  • Consistent exception propagation patterns

1.3. Detailed Component Architecture

This section provides a more detailed view of the system components and their interactions:

Diagram

1.4. Service Interactions

The Service API components interact with each other and with external systems in several key flows:

1.4.1. Request Handling Flow

Diagram

1.4.2. Error Handling Flow

Diagram

1.5. API Capabilities

The Service API provides a comprehensive set of capabilities:

1.5.1. Wireless Management

  • Configure wireless networks (SSID, security type, encryption)

  • Retrieve current wireless settings

  • Enable/disable wireless networks

  • Configure wireless security settings (WEP, WPA, WPA2, etc.)

  • Set wireless encryption keys

  • Configure advanced wireless settings (channel, auto channel, etc.)

1.5.2. Port Management

  • Create port mappings for port forwarding

  • Update existing port mappings

  • Delete port mappings

  • Retrieve current port configuration

  • Validate port configuration

1.5.3. Subscription Management

  • Activate/deactivate service subscriptions

  • Configure subscription parameters

  • Retrieve subscription status

  • Manage multiple service types (wireless, VoIP, internet, IPTV)

1.5.4. Network Mapping

  • Discover connected devices

  • Retrieve device details (IP address, MAC address, hostname)

  • Determine connection type and status

1.5.5. Diagnostics

  • Execute ping tests to verify connectivity

  • Configure ping test parameters

  • Run speed tests to measure connection performance

  • Measure upload and download speeds

  • Retrieve test results and statistics

1.5.6. Device Initialization

  • Initialize new devices

  • Configure basic device parameters

  • Verify device connectivity

  • Set up port mappings

1.5.7. User Authentication

  • Validate user credentials

  • Retrieve user details

  • Find user by email

  • Get IP address information

  • Associate devices with users

1.6. Error Handling

The API implements a comprehensive error handling strategy:

1.6.1. Error Code System

The system uses standardized error codes to indicate different types of failures:

Error Code Status Name Description

100

Completed

SUCCESS

Operation was performed successfully

200

Failed

FAIL

Operation was failed

201

Failed

NO_CPE

No CPE (Device not found or offline)

201

Failed

USER_EXISTS

Username already exists

201

Failed

USER_NOT_EXISTS

Username doesn’t exists

202

Failed

NO_DB

No DB (Database error)

203

Failed

INCORRECT_REQUEST

Incorrect request

203

Failed

INCORRECT_REQUEST_STRUCTURE

Incorrect request structure, non-writable parameter or node

204

Failed

GENERAL

General error

205

Failed

NO_ACS

No ACS (ACS system unavailable)

206

Failed

NO_CPE_NEW_SN

No CPE for NewSN

207

Failed

NO_CPE_CURR_SN

No CPE for CurrSN

401

Failed

UNAUTHORISED

Wrong username or password

1.6.2. Exception Hierarchy

The exception handling system follows a hierarchical approach:

  • FtApiException: Base exception for all API errors

  • FtServiceApiException: Service-level exceptions

    • FtApiLogicLayerException: Business logic exceptions

  • FtApiDataLayerException: Data access exceptions

All exceptions include: * Error code * Descriptive message * Status indicator

1.6.3. Error Response Format

All API error responses follow a consistent format:

  • status: Operation status (Failed, Completed, Rejected, Pending)

  • responseCode: Numeric error code

  • message: Human-readable error message

1.7. Integration with External Systems

The API integrates with external systems primarily through the TR-069 protocol:

1.7.1. NBI API Integration

  • Uses REST API to communicate with NBI API system

  • Sends device parameter updates

  • Retrieves device information

  • Manages device operations

  • Tracks transaction status

1.7.2. Database Integration

  • Uses JDBC to access multiple databases

  • Stores and retrieves device information

  • Manages user credentials and associations

  • Tracks configuration history

  • Stores transaction records