Architecture Overview

This article is for implementation consultants and engineers who need to understand how VersionForge is built. It covers the internal engine, pipeline stages, connector model, multi-tenancy, API surface, and security architecture.

The HGF Engine

Under the hood, VersionForge runs on HGF (HueGo Framework), a TypeScript pipeline engine built on Next.js 14 with Prisma as the data layer. HGF manages the full lifecycle of a sync run -- from extraction through verification -- and provides the connector interfaces, diffing algorithms, snapshot storage, and audit logging.

Key technology choices:

• Next.js 14 (App Router) -- Server components for the dashboard UI; API routes for programmatic access
• Prisma -- Type-safe ORM for PostgreSQL, managing connections, sync profiles, runs, snapshots, and audit records
• TypeScript -- End-to-end type safety from connector interfaces through API responses

Pipeline Flow

Every sync run progresses through seven stages in sequence. If any stage fails, the pipeline halts and the run is marked with the failing stage for investigation.

Extract --> Stage --> Diff --> Transform --> Review --> Load --> Verify

Extract

The source connector pulls data from the external system using the configured credentials and query parameters. Extraction is paginated for large datasets and uses connector-specific APIs (REST, SOAP, XML, or file read).

Stage

The extracted data is written to staging storage in chunked snapshots. Each chunk is hashed using a canonical hashing algorithm to guarantee integrity. Staging decouples extraction from processing -- if downstream steps fail, the source does not need to be queried again.

Diff

The current staged snapshot is compared row-by-row against the previous snapshot for the same sync profile. Rows are matched on the configured diff key (one or more fields that uniquely identify a record). The output is a changeset of adds, updates, and deletes with field-level granularity.

Transform

Field mappings and business rules from the sync profile are applied to the changeset. This includes column renaming, value translation, default fill, concatenation, and any custom transform logic defined in the profile.

Review (Safety Gate)

The transformed changeset is presented in the Safety Gate for human-in-the-loop review. The pipeline pauses here until a reviewer approves, partially approves, or rejects the changeset. This stage is not optional and cannot be bypassed programmatically.

Load

The approved changeset is pushed to the target system via the target connector. For Adaptive Planning, this uses the XML API importConfigurableModelData endpoint with pipe-delimited payloads in 100-row batches. For Pigment, it uses the dataset import API. Load operations are idempotent where the target API supports it.

Verify (Cross-Check)

After load completes, VersionForge runs automated cross-check reconciliation. Source totals from the staged snapshot are compared against target totals queried from the target system. Variances within the configured tolerance pass; variances beyond tolerance flag the run for review.

Connector Model

VersionForge uses a registry pattern for connectors. Each connector implements one of two TypeScript interfaces:

interface ISourceConnector {
  testConnection(): Promise<ConnectionTestResult>;
  getSchema(): Promise<SchemaDefinition>;
  extract(params: ExtractParams): AsyncIterable<DataChunk>;
}

interface ITargetConnector {
  testConnection(): Promise<ConnectionTestResult>;
  getSchema(): Promise<SchemaDefinition>;
  load(changeset: ApprovedChangeset): Promise<LoadResult>;
  queryTotals(params: CrossCheckParams): Promise<TotalSet>;
}

Connectors register themselves with the connector registry at startup. The pipeline engine resolves the correct connector at runtime based on the connection's system type. This makes adding new connectors straightforward -- implement the interface, register it, and the rest of the pipeline works without modification.

Available source connectors: NetSuite, Workday HCM, Stripe, CSV Available target connectors: Adaptive Planning, Pigment In development: Salesforce (source)

Multi-Tenant Architecture

VersionForge is multi-tenant by default. Each tenant (organization) has isolated data at the database level via Prisma's row-level filtering. Connections, sync profiles, runs, snapshots, and audit logs are all scoped to a tenant ID. There is no cross-tenant data access.

Tenant isolation extends to the API layer -- every API request is authenticated and scoped to the caller's tenant. Admin users within a tenant can manage connections and profiles; editor users can trigger runs and review in the Safety Gate; viewer users have read-only access.

API

VersionForge exposes a RESTful API for programmatic access. Key endpoints include:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/connections | GET, POST | List or create connections | | /api/connections/:id/test | POST | Test a connection's credentials | | /api/sync-profiles | GET, POST | List or create sync profiles | | /api/sync-profiles/:id/run | POST | Trigger a sync run | | /api/runs/:id | GET | Get run status, stage, and results | | /api/runs/:id/review | POST | Submit Safety Gate approvals | | /api/runs/:id/cross-check | GET | Get cross-check verification results |

All API requests require a Bearer token in the Authorization header. Tokens are scoped to a tenant and a permission level.

Security

VersionForge applies defense-in-depth across the stack:

• Credential encryption -- All connection credentials are encrypted at rest using AES-256. Decryption occurs only at runtime, in memory, during connector execution.
• API tokens -- Scoped, rotatable tokens for programmatic access. Tokens can be restricted to specific sync profiles or read-only operations.
• Security headers -- All responses include Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, and Content-Security-Policy headers.
• Audit logging -- Every action (connection created, run triggered, Safety Gate approval, override applied) is logged with the actor identity, timestamp, and tenant ID.
• No credential exposure -- Credentials are write-once in the UI. After initial entry, they are masked and cannot be retrieved -- only replaced.