Architecture Overview

1. Architecture Overview

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

1.1. System Context

The Northbound API serves as an integration layer between carrier/service provider’s back-office systems (OSS, billing, CRM,) and underlying ACS systems. It provides both XML/SOAP and REST APIs for provisioning network services, managing devices, and retrieving device information while abstracting the complexity of backend systems.

1.1.1. Business Purpose

  • Automates immediate provisioning of new customer services by pushing configuration updates directly to customer devices

  • Shortens support‑call handling time by giving CSRs real‑time access to current device settings

  • Maintains a persistent mapping between back‑office user IDs and device serial numbers for reliable identification

1.1.2. API Overview

The Northbound API exposes a bidirectional XML/SOAP web‑service interface (ServerWS) that links carrier back‑office systems — CRM, OSS, and BSS — with ACS. External applications send synchronous requests to the API and receive Success/Fail responses; the server can also push asynchronous notifications when required.

The Northbound API supports two interface styles to accommodate different integration needs:

  • XML/SOAP Interface: Traditional web services interface using SOAP protocol

  • RESTful Interface: Modern JSON-based REST API

The API exposes the following core operations:

  • Send Device Parameters – push configuration parameters to one or many devices

  • Download Files – deliver firmware or configuration files to target devices or groups

  • Get Device Parameters – retrieve single parameters or entire objects (with all children) from a device

  • Device Lookup – locate a device using credentials such as phone number, username, or customer name

  • Create Device – add a new device record

  • Delete Device – remove an existing device record

  • Check Device Online – verify current connectivity status

  • Check Update Status – query provisioning/update results

All operations adhere to a uniform response contract: the API returns Success or Fail along with a numeric error code when a request fails.

Authentication

API authentication is optional and controlled through the api.properties file (api.settings.auth).

XML Tag Purpose

Creator

Username for authentication (required when authentication is enabled)

CreatorPassword

Password or SHA‑256 hash (required when authentication is enabled)

1.1.3. System Context Diagram

system-context-diagram

1.2. Component Architecture

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

1.2.1. Architectural Layers

component-architecture-diagram

1.2.2. Key Components in Detail

API Layer (Controllers)

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

  • Exposing both RESTful and SOAP endpoints

  • Handling HTTP requests and producing appropriate responses

  • Validating incoming request data

  • Applying security controls (authentication and authorization)

  • Transforming domain objects to DTOs for API responses

  • Implementing proper error handling and status codes

  • Documenting API endpoints using OpenAPI/Swagger annotations

1.2.3. API Capabilities

The Northbound API provides a comprehensive set of capabilities for device and service management:

Device Parameter Management

  • Set Device Parameters: Send configuration parameters to devices

  • Set individual parameters or parameter groups

  • Control session behavior (end session after update)

  • Specify provisioning options and priorities

  • Validate parameter values before sending

  • Get Device Parameters: Retrieve parameters from devices

  • Get parameters by name or parameter path

  • Retrieve parameter values, attributes, or names

  • Specify data source (cached or realtime from device)

  • Retrieve parameters by transaction ID

  • Parameter Operations:

  • Check parameter values against rules or constraints

  • Set factory default values

  • Reset parameters to default values

  • Apply parameter templates to devices

Device Management

  • Device Information:

  • Create device records in the system

  • Update device information (model, software version, etc.)

  • Delete device records

  • Query device status (online/offline)

  • Find devices by various identifiers (serial number, MAC address)

  • File Operations:

  • Download files to devices (firmware, configuration files)

  • Schedule file transfers with specific timing

  • Check file transfer status

  • Associate files with specific device models

  • Device Discovery:

  • Find devices by credentials (phone number, username, etc.)

  • Discover devices on the network

  • Verify device connectivity

User Information Management

  • User Profiles:

  • Link user information to devices

  • Update user credentials (username, password)

  • Associate custom parameters with users

  • Map service provider user IDs to device identifiers

Transaction Management

  • Status Monitoring:

  • Track operations via transaction IDs

  • Query transaction status

  • Get transaction history

  • Receive notifications about transaction completion

The API design follows these principles:

  • Dual Interface Styles:

  • SOAP/XML interface for legacy system integration

  • RESTful interface for modern applications

  • REST Design Principles:

  • Resource-oriented endpoints (e.g., /devices, /services)

  • Standard HTTP methods (GET, POST, PUT, DELETE) for CRUD operations

  • HTTP status codes for indicating success or failure

  • Consistent request and response formats

  • Pagination for list endpoints

  • Filtering and sorting capabilities

  • Versioning for backward compatibility

  • SOAP Interface Principles:

  • Standard WSDL-based interface

  • XML message format

  • Operation-oriented design

  • Comprehensive error handling

  • Transaction support

Service Layer

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

  • Implements business rules and domain logic

  • Manages transactions across repositories

  • Coordinates calls to external systems

  • Applies data transformations between persistence and API models

  • Implements caching strategies

  • Handles business validation and rules enforcement

  • Publishes domain events for significant state changes

  • Provides a clean API for the controller layer

The service layer design follows these principles:

  • Interface-based design with separation between interface and implementation

  • Single responsibility principle for services

  • Transaction boundaries at the service level

  • Domain service vs. application service separation

  • Immutable value objects where appropriate

  • Domain events for significant state changes

Repository Layer

The repository layer handles data access and persistence:

  • Provides data access objects (DAOs) for domain entities

  • Defines query methods for retrieving data

  • Maps between relational data and domain objects

  • Participates in transaction management

  • Implements efficient data access patterns

  • Handles database-specific optimizations

The repository design follows these principles:

  • Spring Data JPA repositories for common CRUD operations

  • Custom repository implementations for complex queries

  • Query methods for simple queries

  • JPQL/HQL for more complex queries

  • Specification pattern for dynamic queries

  • Pagination and sorting support

Integration Layer

The integration layer handles communication with external systems:

  • Implements clients for external APIs and services

  • Handles protocol-specific details (REST, SOAP, etc.)

  • Transforms data between internal and external formats

  • Implements resilience patterns (circuit breakers, retries, fallbacks)

  • Monitors and logs integration activities

  • Handles authentication and security for external services

The integration layer follows these principles:

  • Facade pattern for simplifying complex integrations

  • Adapter pattern for converting between different interfaces

  • Circuit breaker pattern for handling external system failures

  • Retry pattern for transient failures

  • Timeout handling for unresponsive systems

  • Monitoring and health checks for integration points

1.3. Database Architecture

The application uses a multi-database architecture to separate concerns and integrate with existing systems:

1.3.1. Multi-Database Design

database-architecture-diagram

1.3.2. Database Content and Purpose

  • ACS Database:

  • Core provisioning and device configuration data

  • Device inventory and status tracking

  • Device models and capabilities

  • Configuration templates and parameters

  • Service definitions and parameters

  • Provisioning workflows and status

  • Customer service mappings

1.4. Security Architecture

The application implements a comprehensive security architecture to protect API resources:

1.4.1. Authentication Mechanisms

The Northbound API supports multiple authentication mechanisms to accommodate different integration scenarios:

API Authentication

The API authentication is configured via the api.properties file with the following options:

  • Login Authentication: When enabled (api.settings.auth=true), requests must include:

  • Creator tag: Contains the username for authentication

  • CreatorPassword tag: Contains the password (or SHA256 hash of password) for authentication

authentication-flow-diagram

1.5. Error Handling Architecture

The application implements a comprehensive error handling framework:

1.5.1. Request Handling and Message Flow

The Northbound API handles both SOAP and REST requests through specialized components that ensure consistent processing, authentication, and error handling:

SOAP Request Handling
soap-request-handling-diagram
REST Request Handling
rest-request-handling-diagram
Message Exchange Formats

The Northbound API supports two primary message exchange formats:

  • SOAP/XML Format:

  • XML-based message structure

  • Uses SOAP envelope with header and body sections

  • Includes authentication credentials in request

  • Returns standardized success/failure responses

  • Error codes and descriptions in SOAP fault elements

  • REST/JSON Format:

  • JSON-based message structure

  • JWT token authentication in Authorization header

  • Standard HTTP status codes for success/failure

  • Consistent error response structure

  • Resource-oriented URL structure

Success/Failure Responses

All API operations respond with a standardized success/failure format:

  • Success Response:

  • Status code indicating success

  • Requested data (if applicable)

  • Transaction ID for tracking (when relevant)

  • Failure Response:

  • Error code indicating the nature of the failure

  • Human-readable error message

  • Details for troubleshooting

  • Reference information for support

1.6. Integration with Other Friendly Modules

The application integrates with other Friendly modules:

  • ft-exceptions: Standard exception handling

  • shared-dto: Common DTOs for API consistency

  • api-orm: ORM utilities

  • api-common: Common utilities

  • acs-api-client: Client for ACS API

  • ft-cache: Caching utilities