Skip to content
Back to Blog
architecture control-plane engineering

Introducing the QuickBridge Control Plane

How we're moving from a Django monolith to a Tunnel-owned control plane — and why it matters for reliability, speed, and African enterprise integrations.

QuickBridge Team |

For the past year, QuickBridge has been running a dual-system architecture: a Django Backend (the “Bridge”) that owns organisations, connections, and integrations, and a Node.js Tunnel that executes the actual sync workflows — eZee to QuickBooks, EFRIS e-invoicing, InstaHMS, and more.

Every time the Tunnel needed to know which connection to use or what credentials to authenticate with, it called back to the Bridge over HTTP. That worked. Until it didn’t.

The problem with remote config

Three things kept breaking:

  1. Latency. A sync workflow that fetches 500 invoices from eZee and posts them to QuickBooks Desktop shouldn’t need 3 round-trips to the Bridge just to resolve connection credentials. At P99, those calls added 200ms+ of overhead per run.

  2. Availability coupling. If the Bridge was down for a deploy or a database migration, the Tunnel couldn’t resolve connections. Syncs failed — not because the source or target was unreachable, but because the config layer was offline.

  3. Schema drift. The Bridge stored connections in Django’s core_connection table with fields like identifier, date_deleted, and integer primary keys. The Tunnel expected UUIDs, kind, and enabled. Every provider had a mapping layer that papered over the differences.

What we built

The Control Plane is a set of Postgres tables owned by the Tunnel, living in a control_plane schema in the same database:

CREATE SCHEMA IF NOT EXISTS control_plane;

-- Organisations, Connections, Integrations
-- Cursors (sync state), Audit Events (observability)

The key tables:

  • control_plane.organisations — Identity and scoping. UUID primary key, name, slug.
  • control_plane.connections — Credentials, kind, org reference, enabled flag, metadata JSONB.
  • control_plane.integrations — Source/target connection pairs, org reference, enabled flag.
  • control_plane.cursors — Sync state (last cursor per integration + connection + key).
  • control_plane.audit_events — Every sync run, every failure, every lifecycle change.

Data was migrated from the Django tables with idempotent SQL scripts:

pnpm run db:control-plane  # creates tables + migrates data

What changes for the Tunnel

The Tunnel’s DatabaseConnectionProvider and DatabaseIntegrationProvider now read from control_plane.* instead of Django’s core_connection / core_integration. The provider interface stays the same — consumers (workflows, interceptors, controllers) don’t change.

The next step: Zod-backed DTOs with strict ConnectionKind unions and per-kind credential validation. When a connection is loaded from the database, its credentials are validated against the expected shape for that connector type. Invalid data fails at the boundary, not in a worker 3 steps later.

Why this matters

For the teams running QuickBridge in production — syncing hotel POS data to QuickBooks, submitting e-invoices to EFRIS, bridging laboratory systems to accounting — the control plane means:

  • Faster syncs. No HTTP round-trip to resolve config. Connection data is a local DB read.
  • Independent deploys. The Tunnel doesn’t need the Bridge to be running to sync.
  • Validated config. Zod schemas catch misconfigured connections before they reach a workflow.

We’re not done — the Bridge still handles the Portal UI and OAuth flows — but the critical path for sync execution is now fully Tunnel-owned.

This is the first in a series of engineering posts about the QuickBridge architecture. Next up: how we’re using Zod discriminated unions to validate connector credentials at the database boundary.