System Components Overview

Overview

The OneIoT Web Backend is a multi-component system that integrates with several external services. This page describes the system components and the application directory structure for local (non-Docker) deployments.

System Components

Component Technology Purpose

UI Backend

Spring Boot 3.5, Java 25

REST API for device management, provisioning, settings

UI Portals

Angular / Nginx

Support Center and Management Console web interfaces

FTACS Database

MySQL 8.0+ / Oracle 21c+

ACS configuration data (devices, parameters, templates)

IOTW Database

MySQL 8.0+ / Oracle 21c+

UI application data (users, views, settings)

ClickHouse

ClickHouse (optional)

QoE analytics and monitoring data

ACS (FTACS)

SOAP WebService

Device communication via TR-069 / TR-181 / LWM2M / USP

Hazelcast

Hazelcast Cluster

Distributed caching and session clustering

Application Directory Structure

The dist folder contains everything needed to run the application locally (without Docker). The tree below shows the baseline layout plus common environment-dependent entries in conf/:

dist/
├── bin/
│   ├── app.env              # Main configuration (paths, DB, ACS, Hazelcast)
│   └── start.cmd / start.sh # Startup scripts
├── conf/
│   ├── hazelcast-client.xml # Main Hazelcast cluster configuration
│   ├── ftacs.keystore       # Backend keystore used when HTTPS is enabled
│   ├── logback-spring.xml   # Default external logging configuration
│   ├── interfaceItems.json  # Interface seed data, loaded if present
│   └── customization/       # Portal customization files
│       ├── def/             # Default system-wide customizations
│       ├── mc/              # Management Console customizations
│       └── sc/              # Support Center customizations
├── app/                     # Built application (backend WAR/JAR + Angular UI)
├── ext/                     # External libraries (rarely updated)
├── liquibase/               # Database and ACS migration changesets
└── logs/                    # Application log files

Key Configuration Files

File Description

bin/app.env

Main environment configuration: APP_HOME, JAVA_HOME, database connection, ACS credentials, Hazelcast members

conf/hazelcast-client.xml

Baseline Hazelcast client configuration with cluster member addresses

conf/ftacs.keystore

Backend keystore used by the embedded application server when HTTPS is enabled

conf/logback-spring.xml

Default external logging configuration loaded at startup

conf/interfaceItems.json

Seed file used to initialize interface item metadata when present

conf/customization/

JSON files controlling portal appearance and features per client type (def, mc, sc)

Troubleshooting

Database Connection Error

Symptom: Application fails to start with JDBC connection errors.

Solution:

  • Verify DB_HOST, DB_USER, DB_PASSWORD in bin/app.env

  • Ensure the database server is running and accessible

ACS Connection Error

Symptom: SOAP calls to ACS fail or timeout.

Solution:

  • Verify ACS_WEB_SERVICE_HOST and credentials in bin/app.env

  • Ensure the FTACS service is running on the expected port

Application Does Not Start

Symptom: start.sh / start.cmd exits immediately.

Solution:

  • Check script permissions: chmod +x bin/start.sh

  • Verify JAVA_HOME points to a valid JDK 25+ installation

  • Check logs/ for detailed error messages