Skip to content

Deployment Topologies

Applies to: All subscriptions

Purpose

Set out the deployment shapes a Complifly installation can take, what each implies for availability, scaling, maintenance and cost, and give a defensible basis for choosing one.

Audience

Solution architects, infrastructure leads, and the customer's IT decision-maker.

Prerequisites

  • System Architecture
  • An estimate of document volume and of how much downtime the business will tolerate

Reference

Topology A — single host

Everything on one server: application API, background worker, and optionally the database.

  +--------------------------------------------+
  |  One host                                  |
  |  proxy + API + worker (+ database)         |
  +--------------------------------------------+
Suits Pilots, proofs of concept, low-volume single-entity customers, non-production environments
Availability None. Any restart is an outage
Scaling Vertical only
Maintenance Every change is a full outage
Watch for The database competing with the application for memory. Collocating the database is acceptable for a pilot and a poor idea in production

Application and worker on an application host; the database on its own managed or dedicated instance.

  +----------------+        +--------------------+
  | Application    |        |  Database host     |
  | host           |------->|  (managed or       |
  | proxy+API+     |        |   dedicated)       |
  | worker         |        |  backup, HA        |
  +----------------+        +--------------------+
Suits The majority of production customers
Availability Database availability handled by the database platform; the application tier remains a single point of failure
Scaling Application host vertically; the database independently
Maintenance Application restarts are short; database maintenance follows the database platform's own model
Why this is the baseline It separates the only stateful component from the disposable ones. Backup, restore, recovery objectives and isolation policies all live with the database, where they belong

Topology C — scaled out

Multiple API instances behind a load balancer, with a single worker.

                      +-------------------+
   clients ---------> |  Load balancer    |
                      +-------------------+
                        |       |       |
                     API-1    API-2   API-3      (stateless, no stickiness)
                        \       |       /
                         \      |      /
                       +---------------------+
                       |   Database (HA)     |
                       +---------------------+
                                 ^
                       +---------------------+
                       |  Worker (single)    |
                       +---------------------+
Suits High document volume, or an availability requirement the application tier must meet
Availability API instances can be lost or restarted individually; rolling deployment becomes possible
Scaling Add API instances freely — they are stateless and need no session affinity
The constraint The worker. Until concurrent workers are confirmed supported, run exactly one. Scale the API; do not scale the worker

Verify: Whether multiple concurrent worker instances are supported against one database has not been confirmed. Work is claimed with database leases, which is the right foundation for it, but that is not the same as a supported configuration. Until Complifly confirms, run one worker. Recorded as assumption C4 in the Assumptions Register.

Environments

Whichever topology is chosen for production, plan for at least three:

Environment Purpose Provider credentials Notes
Development / sandbox Integration build, mapping template development Provider sandbox Never point this at production government credentials
Test / UAT Business validation, user training, upgrade rehearsal Provider sandbox Should mirror production topology closely enough that an upgrade rehearsal is meaningful
Production Live compliance Production credentials Change-controlled

The single most common and most expensive environment mistake is a non-production environment configured with production provider credentials. A test invoice then reaches NIC, consumes a real document number permanently, and cannot be undone. Make the separation structural, not a matter of care.

Choosing

If Choose
Pilot, or a non-production environment A
Production, single entity, moderate volume B
Production with an availability requirement, or high volume C
Business cannot tolerate a maintenance-window outage C, and rehearse a rolling upgrade before you need one
Volume is genuinely unknown B, sized to grow, with monitoring in place from day one

Validation

Before signing off a topology:

Check Pass condition
Recovery objectives are written down Recovery point and recovery time objectives are stated numerically and the chosen topology can meet them
The database platform meets them Backup frequency, retention and restore time have been tested, not assumed
Exactly one worker is active Confirm by process inventory across all hosts, not by intention
API instances need no stickiness Disable session affinity in the load balancer and confirm the application still behaves
Environments are separated A test environment cannot reach production government credentials — verified by attempting it, not by inspecting configuration
Maintenance is rehearsed A restart and an upgrade have both been performed in a non-production environment and timed
Monitoring exists before go-live The checks in Monitoring and Health Checks are configured, not planned

Troubleshooting

Symptom Cause Action
Intermittent errors after adding a second API instance Load balancer configured with session affinity, masking a real fault; or two workers now running Disable affinity and inventory worker processes across hosts
Background jobs processed twice More than one worker active Reduce to one. Leases limit the damage but are not a licence to run several
Application slows as document volume grows, database looks idle Application tier saturated; the database is not the bottleneck Move from A to B, or from B to C
Database slows while the application looks idle Database undersized, or missing maintenance See Database Requirements and Monthly Checks
A test invoice appears at NIC Non-production environment holding production credentials Treat as an incident. The document number is permanently consumed; the invoice cannot be un-registered. Separate the environments before doing anything else
Upgrades consistently overrun the window Single-host topology forces a full outage for every change Move to C and adopt rolling deployment, or negotiate a longer window with measured evidence
Restore into a test environment leaves users seeing nothing Tenant identifiers differ between environments Reconcile scope identifiers. Never disable isolation policies to work around it. See Multi-Tenancy and Row-Level Security