Integration Architecture

How INTERA talks to external systems #

INTERA communicates with external systems through Integration Modules. Each Integration Module acts as a controlled adapter between INTERA Core and one external system, service, database, file source, or data provider.

The external system may be a billing platform, accounting system, CRM, ERP, ticketing system, fleet management system, shipmanagement system, navigation platform, logistics platform, or another business application. INTERA does not require the external system to follow INTERA’s internal data model. Instead, the Integration Module translates the external system’s structure into datasets, entities, and values that INTERA can understand.

At runtime, INTERA works with configured Integration Instances. An Integration Instance contains the specific connection settings for one customer environment, such as API URL, credentials, database connection, tenant ID, file path, sync settings, and enabled DataSources.

The usual flow is:

External System
    ↓
Integration Module
    ↓
Integration Instance
    ↓
DataSources / Entity Providers
    ↓
INTERA Assets, Metrics, Dashboards, Rules, and Role Packages

This design keeps INTERA non-intrusive. In most cases, INTERA reads data from existing systems without changing their internal logic, ownership, workflows, or user permissions.

Read-only vs write-capable integrations #

Most INTERA integrations should be read-only by default.

A read-only integration allows INTERA to collect operational data, synchronize entities, calculate Metrics, display dashboards, detect patterns, and support reconciliation without writing anything back to the external system. This is the safest and most common integration model.

Read-only integrations are suitable for:

- dashboards
- Metrics
- entity synchronization
- reconciliation checks
- operational health indicators
- pattern detection
- reporting
- alerts and notifications

A write-capable integration allows INTERA to send commands, updates, or actions back to the external system. This may include creating a ticket, updating a status, triggering a workflow, sending a comment, changing a flag, or executing an approved action.

Write-capable integrations require stricter review because they can affect external systems directly. They should only be used when the action is clearly defined, permission-controlled, auditable, and safe to repeat or recover from.

A developer should not assume that an integration is write-capable unless this is explicitly declared and approved.

The recommended approach is:

Default mode: read-only
Optional mode: write-capable, only for approved actions

Even when an external system supports write operations, an INTERA Integration Module may expose only read functionality if that is sufficient for the role package or dashboard use case.

API integrations #

API integrations connect to external systems through HTTP APIs, SDKs, or other service interfaces.

This is the preferred integration type when the external system provides a stable, documented API. API integrations are commonly used for SaaS platforms, cloud services, modern billing systems, CRMs, ticketing platforms, accounting software, fleet systems, and monitoring platforms.

An API integration usually handles:

- authentication
- request signing or token management
- pagination
- filtering
- rate limits
- retry logic
- response transformation
- error handling

For example, a billing API may expose invoices, customers, payments, services, and usage records. The INTERA Integration Module can wrap those API endpoints into clean DataSources such as:

customers
invoices
payments
active_services
usage_summary

The goal is not to expose the external API exactly as it exists. The goal is to expose stable business datasets that INTERA dashboards, Metrics, and role packages can use reliably.

An API integration should hide unnecessary API complexity from INTERA. For example, if the external system requires multiple API calls to calculate a customer balance, the Integration Module should perform that logic internally and return a clean result.

File-based integrations #

File-based integrations read data from structured files produced by external systems.

This model is useful when the external system does not have an API, when API access is limited, or when the organization already uses scheduled exports. Common file formats include:

- CSV
- TXT
- XLS / XLSX
- JSON
- XML
- fixed-width legacy files

Files may be retrieved from:

- local folders
- shared folders
- SFTP / FTP servers
- cloud storage
- email attachments
- scheduled export locations
- URLs

A file-based Integration Module is responsible for locating the file, validating its format, parsing its contents, normalizing field names, handling missing or invalid values, and returning structured data to INTERA.

File-based integrations should be designed carefully because files can change without notice. Column names may be renamed, formats may shift, dates may appear in different formats, and exports may be incomplete.

A good file-based integration should therefore include:

- expected file format documentation
- required columns
- optional columns
- validation rules
- clear error messages
- sample files
- handling for empty files
- handling for duplicate rows

File-based integrations are especially useful for legacy systems where direct system access is not available but scheduled exports can be produced reliably.

SQL/database integrations #

SQL or database integrations connect directly to a database or database view.

This model is useful when the external system stores data in a database that can be accessed safely in read-only mode. Examples include internal billing platforms, ERP backends, operational databases, custom business systems, and legacy platforms.

A database integration may connect to systems such as:

- PostgreSQL
- MySQL / MariaDB
- Microsoft SQL Server
- Oracle
- SQLite
- other supported SQL databases

In most cases, SQL integrations should use a read-only database user. INTERA should not require direct write access to operational databases for normal dashboard, Metric, or synchronization use cases.

A SQL integration may expose DataSources based on predefined queries, views, or stored procedures. For example:

DataSource: overdue_invoices
Query source: finance.v_overdue_invoices
Filters:
- from date
- to date
- customer ID
- currency

SQL/database integrations must be designed with security and performance in mind. Developers should avoid exposing arbitrary SQL execution to dashboard users or role packages. Queries should be controlled by the Integration Module, and runtime parameters should be validated before use.

Recommended rules:

- use read-only database credentials;
- expose predefined DataSources, not unrestricted database access;
- validate all parameters;
- avoid long-running queries;
- use database views where possible;
- return predictable result shapes;
- document expected fields and filters.

SQL integrations can be powerful, but they must be treated as controlled business interfaces, not as open access to the customer’s database.

Sync model #

INTERA supports two main ways of using external data:

1. On-demand access through DataSources
2. Synchronized entities through Entity Providers

A DataSource is used when INTERA needs live or near-live data for a dashboard, widget, Metric calculation, reconciliation rule, or report. The DataSource is called when needed and returns the requested dataset.

Entity synchronization is used when INTERA needs to maintain a local representation of important business objects. These objects become INTERA Assets or support Asset Mapping. Examples include customers, vessels, products, suppliers, contracts, services, trucks, employees, sites, or equipment.

The difference is important:

DataSource = request data when needed
Entity Sync = import and maintain business objects locally

For example, a dashboard widget showing “Invoices due this week” may use a DataSource. A customer list used across many dashboards, rules, and mappings may be synchronized as entities.

A typical sync flow is:

1. INTERA calls the Integration Instance.
2. The Integration Module connects to the external system.
3. The Entity Provider returns a structured list of external entities.
4. INTERA matches each external entity to a local Asset or entity record.
5. INTERA updates local payloads and timestamps.
6. Missing entities may be marked inactive rather than deleted.
7. Metrics and dashboards can use the updated data.

Synchronization should be predictable and repeatable. Developers should avoid returning unstable identifiers, inconsistent field names, or partially transformed data that changes shape between sync runs.

For most integrations, sync should be treated as a full or controlled snapshot of a specific entity type. The Integration Module should clearly document what entity type is returned, what field acts as the stable key, and how often the data should be refreshed.

Good sync design requires:

- stable external identifiers;
- clear entity type names;
- predictable payload structure;
- last update timestamps where available;
- handling for missing, disabled, archived, or deleted records;
- clear sync error reporting;
- reasonable limits and pagination.

Time context / period contract #

Many business values only make sense when the time period is clear.

For example, the phrase “revenue” is incomplete unless INTERA knows whether it means today, this week, this month, previous billing period, invoice issue period, payment period, financial quarter, voyage period, shift, or custom operational window.

INTERA therefore uses a time context, also called a period contract, to define which time period a DataSource, Metric, reconciliation rule, or role package is operating on.

Examples of time contexts include:

- current calendar month
- previous calendar month
- billing period
- invoice issue date range
- payment date range
- due date range
- voyage period
- production shift
- delivery window
- ticket creation period
- ticket resolution period
- financial quarter

Different external systems may use different time models. A billing system may organize data by billing period. An accounting system may organize invoices by issue date, due date, payment status, or posting date. A logistics system may use delivery windows. A shipmanagement system may use voyage dates, certificate expiry dates, or maintenance periods.

For this reason, an Integration Module should clearly declare which time filters each DataSource supports.

For example:

DataSource: invoices
Supported time filters:
- invoice_issue_date_from
- invoice_issue_date_to
- due_date_from
- due_date_to
- payment_date_from
- payment_date_to

A Metric should also be calculated against an explicit time context.

For example:

Metric: monthly_revenue
Asset: customer
Time context: billing_period = 2026-06
Value: 12,500 EUR

This avoids ambiguous values and makes dashboards more reliable. It also allows role packages to reuse the same integration data in different ways.

A finance role may care about invoice issue dates and payment status. A sales role may care about order dates and forecast periods. An operations role may care about delivery dates, service activation dates, or ticket resolution periods.

A good Integration Module should therefore:

- document supported time filters;
- use clear field names for date and period parameters;
- avoid vague terms such as “current period” unless the period is explicitly defined;
- return the time period used in the response where appropriate;
- handle timezone and date boundary issues consistently;
- explain how the external system defines billing, accounting, or operational periods.

The time context / period contract is essential for reliable Metrics, reconciliations, trends, alerts, and role-based dashboards.