Digital Twins & GitOps — Building Custom Twin Functions with fnkit

What Is a Digital Twin?

The term "digital twin" is one of the most overloaded phrases in manufacturing technology. It gets applied to everything from a 3D CAD model to a real-time simulation to a simple dashboard. Let's be precise about what it actually means.

A digital twin is a live, software representation of a physical system that evolves in real-time as the physical system changes. It's not a static model. It's not a one-time snapshot. It's a continuously updated mirror of reality — fed by real sensor data, enriched with historical context, and capable of answering questions about the physical system's current state, past behaviour, and future trajectory.

The critical distinction is the live data connection. A CAD model is a digital representation, but it doesn't know whether the physical machine is running, alarming, or producing scrap. A digital twin does. It knows the machine's current state, how long it's been in that state, what program it's running, what tool is loaded, and whether the spindle vibration is trending outside normal parameters.

What a Digital Twin Is Not

A true digital twin combines all of these capabilities — real-time data, historical context, structured state models, derived intelligence, and the ability to influence the physical system — into a single, coherent software entity.

The Three Maturity Levels

The industry has converged on three maturity levels for digital representations of physical systems. Understanding where you are — and where you need to be — determines the architecture you need.

Most manufacturing organisations today are at Level 1 — Digital Shadow. They have dashboards, historians, and SCADA systems that reflect machine state. The fn-uns reference pipeline gives you a solid Level 1 starting point, with a clear path to Level 2 through MQTT's bidirectional pub/sub architecture. But the real power is that fnkit lets you scaffold new twin functions — quality prediction, vibration analysis, thermal compensation, energy monitoring — whatever your specific factory needs to move up the maturity curve.

Why Digital Twins Are Hard

If digital twins are so valuable, why do so few manufacturers have them? The answer isn't technology — it's complexity. Building a digital twin for one machine is straightforward. Scaling that to a factory floor with 100 machines across 5 sites is where every approach breaks down.

The Seven Scaling Problems

The Cost Curve

Here's what happens to complexity and cost as you scale a digital twin — and why the architecture you choose at the start determines whether you succeed or stall:

At one machine, every approach works. The divergence happens around 10–50 machines, when the monolithic platform's complexity grows exponentially while the composable approach scales linearly. By the time you reach multi-site, the monolithic approach requires dedicated teams just to manage the twin infrastructure — while the composable approach is still just git push.

The UNS as the Foundation for Digital Twins

Here's the insight that changes everything: a Unified Namespace is already a digital twin's data backbone. The UNS provides exactly the three things a digital twin needs — a structured representation of physical assets, a real-time data connection, and a historical record.

How UNS Concepts Map to Digital Twin Concepts

The Architecture

The left side is your physical factory. The right side is your digital twin — built from functions you scaffold with fnkit. The MQTT broker is the bridge between them. The dashed green boxes are your custom twin functions — the ones specific to your factory's needs. Every function adds a new cognitive capability to the twin, and because they're independent containers, you can deploy them incrementally.

Building Twin Functions with fnkit

Here's the key idea: your digital twin isn't a product you buy — it's a set of functions you build. The fn-uns reference pipeline gives you a solid starting point — state tracking, historical logging, KPI calculations, stoppage classification. But your factory has problems that are unique to your factory. A CNC shop needs vibration analysis and tool wear prediction. A food plant needs temperature compliance and batch traceability. An assembly line needs cycle time anomaly detection and takt adherence.

fnkit gives you the platform to scaffold whatever twin functions your specific use case needs — in seconds.

The fnkit Scaffold Workflow

# Scaffold a new twin function — one command

# Go HTTP function (for request/response twin queries)
fnkit go uns-quality-predict

# Node.js HTTP function (for analysis endpoints)
fnkit node uns-vibration-alert

# Go MQTT function (for real-time stream processing)
fnkit go-mqtt uns-thermal-comp

# Node.js MQTT function (for event-driven twin logic)
fnkit node-mqtt uns-energy-monitor

Each command creates a complete, deployable function in seconds:

uns-quality-predict/
├── function.go          # Your handler — write your twin logic here
├── cmd/main.go          # Entry point (auto-generated)
├── Dockerfile           # Container build (auto-generated)
├── docker-compose.yml   # Service definition — already on fnkit-network
├── .env.example         # CACHE_URL, DATABASE_URL, MQTT_BROKER
├── go.mod               # Dependencies
├── .gitignore
└── README.md

# The scaffolded function already has:
# ✓ Connection to the shared Valkey cache (same as all other functions)
# ✓ Connection to PostgreSQL (same database, same tables)
# ✓ Docker networking (fnkit-network — can talk to every other function)
# ✓ Dockerfile for containerised deployment
# ✓ GitOps-ready structure (git push deploy main)

Twin Functions You'd Build

The fn-uns reference pipeline handles the fundamentals — state tracking, historical logging, KPIs, stoppage classification. But your twin needs functions specific to your factory. Here are examples of what you'd scaffold:

Your Twin Is a Mix of Reference + Custom

In practice, your digital twin repository looks like this — a mix of fn-uns reference functions and custom functions you've scaffolded for your specific needs:

# Your digital twin — reference pipeline + custom functions

fn-uns/
├── uns-framework/          # Reference: perception layer (Go MQTT)
├── uns-state/              # Reference: state tracking (Go)
├── uns-historian/          # Reference: value change logging (Go)
├── uns-stoppage/           # Reference: downtime classification (Node.js)
├── uns-kpi/                # Reference: KPI calculations (Go)
│
├── uns-quality-predict/    # YOUR TWIN: quality prediction (Go)
├── uns-vibration/          # YOUR TWIN: vibration analysis (Go)
├── uns-thermal-comp/       # YOUR TWIN: thermal compensation (Go MQTT)
├── uns-energy/             # YOUR TWIN: energy monitoring (Node.js)
├── uns-tool-wear/          # YOUR TWIN: tool wear prediction (Go)
│
└── uns-dashboard/          # Visualisation (Grafana)

# Every function — reference or custom — connects to the same
# Valkey cache, the same PostgreSQL database, the same MQTT broker.
# Every function is independently deployable, testable, replaceable.

What Makes This Different from a Platform

Case Study: A CNC Quality Twin

To make this concrete, let's walk through scaffolding and building a quality-focused digital twin function for a CNC machining cell — one of the most complex and valuable twin applications in discrete manufacturing.

The Quality Problem

A CNC machining cell produces precision aerospace components. Quality is measured by dimensional accuracy (±0.01mm tolerances), surface finish (Ra values), and geometric conformance (GD&T). When a part fails inspection, the cost is enormous — not just the scrapped material, but the machine time, the operator time, and the schedule disruption.

The fundamental question is: can we predict quality problems before they produce scrap?

To answer that, you need to correlate data from multiple sources in real-time:

Scaffolding the Quality Twin Function

All of this data is already flowing through the UNS and being captured by the reference pipeline. The quality twin doesn't require new infrastructure — it requires a new function that reads from the existing data and adds intelligence on top.

Here's how you build it:

# Step 1: Scaffold the function
fnkit go uns-quality-predict

# → Creates uns-quality-predict/ with:
#   function.go, cmd/main.go, Dockerfile,
#   docker-compose.yml, .env.example, go.mod

# Step 2: Configure environment
cd uns-quality-predict
cp .env.example .env
# .env already has CACHE_URL and DATABASE_URL
# pointing to the shared fnkit infrastructure

Now write the twin logic in function.go:

// uns-quality-predict/function.go
// Quality prediction twin function — reads from shared cache + DB

func QualityPredict(w http.ResponseWriter, r *http.Request) {
    machine := r.URL.Query().Get("machine")

    // 1. Read current state from Valkey cache
    //    (same cache that uns-framework writes to)
    spindleLoad := cache.Get("uns:v1.0:...:"+machine+":status:spindle_load")
    toolLife    := cache.Get("uns:v1.0:...:"+machine+":tool:life_remaining")
    cycleTime   := cache.Get("uns:v1.0:...:"+machine+":program:cycle_time")

    // 2. Query historical context from PostgreSQL
    //    (same database that historian/state/stoppage write to)
    recentScrap := db.Query(`
        SELECT count, reason, timestamp
        FROM uns_input
        WHERE machine = $1 AND type = 'scrap'
        AND timestamp > NOW() - INTERVAL '2 hours'`, machine)

    wearTrend := db.Query(`
        SELECT value, timestamp
        FROM uns_historian
        WHERE topic LIKE $1
        AND timestamp > NOW() - INTERVAL '4 hours'
        ORDER BY timestamp`, "%"+machine+"%tool%life_remaining")

    lastStoppage := db.Query(`
        SELECT reason, duration_seconds
        FROM uns_stoppage
        WHERE machine = $1
        ORDER BY start_time DESC LIMIT 1`, machine)

    // 3. Compute quality risk score
    risk := computeQualityRisk(spindleLoad, toolLife, cycleTime,
                               recentScrap, wearTrend, lastStoppage)

    // 4. If risk exceeds threshold, publish alert to MQTT
    if risk.Score > 0.7 {
        mqtt.Publish("v1.0/.../"+machine+"/twin/quality-alert", risk)
    }

    // 5. Return prediction as JSON
    json.NewEncoder(w).Encode(risk)
}

# Step 3: Test locally
docker compose up -d
curl http://localhost:8080/uns-quality-predict?machine=cnc-01 | jq

# Step 4: Deploy alongside existing pipeline
git add uns-quality-predict/
git commit -m "add quality prediction twin function

Scaffolded with fnkit go. Reads spindle load, tool life, and
cycle time from Valkey cache. Queries scrap history, wear trends,
and stoppage context from PostgreSQL. Computes quality risk score.
Publishes alert to MQTT when risk > 0.7.

Motivation: 2 scrap events last week correlated with tool wear
on T03 during PART-A-001 finishing ops. This function detects
the pattern automatically and alerts before scrap occurs."

git push deploy main
# → Function is live, reading from the same infrastructure
# → Existing functions are completely untouched

Why This Is Hard Without a UNS

Without a Unified Namespace, building this quality twin requires:

• ✗ Custom integration per data source — one connector for the CNC controller, another for the tool presetter, another for the CMM, another for the MES
• ✗ Manual data correlation — matching a quality measurement to the specific tool, program, and machine conditions at the time of machining
• ✗ No standard data model — every system has its own schema, its own timestamps, its own naming conventions
• ✗ Batch analysis — quality data is typically analysed after the fact, not in real-time. By the time you find the pattern, you've already produced scrap.
• ✗ Siloed knowledge — the operator knows the tool feels "different," the quality engineer sees the measurement trend, the maintenance engineer sees the alarm history — but nobody has the complete picture

With the UNS + fnkit approach, all of this data is already flowing through the same namespace. The quality twin is just a new function on top of existing data — scaffolded in seconds, deployed in minutes, not a new infrastructure project.

Why GitOps Is Essential for Digital Twins

A digital twin is only as trustworthy as the logic that drives it. If you can't answer "who changed the twin's behaviour, when, and why?" — then you can't trust the twin's output. This is where GitOps transforms digital twins from fragile experiments into production infrastructure.

Twin Logic Is Code

Every aspect of your digital twin — reference functions and custom twin functions alike — is code in a git repository:

# Your digital twin is a git repository

fn-uns/
├── uns-framework/          # Perception layer (Go MQTT)
│   ├── function.go         # MQTT subscription + cache logic
│   ├── Dockerfile
│   └── README.md
│
├── uns-state/              # State model (Go)
│   ├── function.go         # State transition detection
│   └── ...
│
├── uns-quality-predict/    # YOUR TWIN: quality prediction (Go)
│   ├── function.go         # Quality risk scoring logic
│   ├── Dockerfile
│   └── ...
│
├── uns-vibration/          # YOUR TWIN: vibration analysis (Go)
│   ├── function.go         # FFT analysis + bearing wear detection
│   └── ...
│
├── uns-thermal-comp/       # YOUR TWIN: thermal compensation (Go MQTT)
│   ├── function.go         # Thermal drift model + warm-up recs
│   └── ...
│
├── uns-energy/             # YOUR TWIN: energy monitoring (Node.js)
│   ├── index.js            # Power draw correlation + waste detection
│   └── ...
│
└── uns-dashboard/          # Visualisation (Grafana)
    └── grafana/            # Dashboard JSON — version-controlled

# Every file is tracked. Every change has an author.
# Every deployment is a git commit.
# Every new twin function is a `fnkit` scaffold + git push.

What GitOps Gives Your Digital Twin

The Twin Drift Problem

One of the most insidious problems with digital twins is drift — the gradual divergence between what the twin thinks is happening and what's actually happening. Drift has two forms:

The Deployment Workflow: Adding a New Twin Capability

# Example: Adding thermal compensation to your digital twin

# 1. Scaffold the new function
fnkit go-mqtt uns-thermal-comp
cd uns-thermal-comp

# 2. Write the twin logic
# function.go: subscribe to temperature topics via MQTT
# Read ambient temp, spindle temp, coolant temp from UNS
# Query uns_historian for dimensional accuracy after idle periods
# Model thermal drift curve for each machine
# Publish warm-up recommendations to MQTT

# 3. Test locally
cp .env.example .env
docker compose up -d
# Verify: function subscribes, processes, publishes correctly

# 4. Commit with full context
git add uns-thermal-comp/
git commit -m "add thermal compensation twin function

Scaffolded with fnkit go-mqtt. Subscribes to temperature topics.
Models thermal drift after startup and long idle periods.
Queries historian for dimensional accuracy correlation.
Publishes warm-up recommendations to v1.0/.../twin/thermal-comp.

Motivation: first-part scrap rate is 3x higher on Monday mornings
and after lunch breaks. Thermal drift from cold spindle is the
likely cause. This function detects the condition and recommends
warm-up cycles before production starts.

Tested: local docker compose with simulated temperature data."

# 5. Push, review, merge
git push origin feature/thermal-compensation
# → Create pull request → Team reviews → Merge to main

# 6. Deploy to all sites
git push deploy main
# → Every site gets the new capability, simultaneously
# → Existing functions are completely untouched

# 7. If something goes wrong at any site
git revert HEAD
git push deploy main
# → Previous version running everywhere in seconds

Scaling Digital Twins with fn-uns

The real test of any digital twin architecture is what happens when you scale. Here's the progression — and why composable functions with GitOps handle each stage gracefully.

1 Machine → 10 Machines

10 Machines → 100 Machines

1 Site → 5 Sites

The Cost Comparison

The Bottom Line

Digital twins don't have to be expensive, vendor-locked, or impossibly complex. The industry has been sold a vision of monolithic platforms that promise everything and deliver pilot projects that never scale. The reality is simpler.

A digital twin needs three things:

• ✓ A structured data backbone — the UNS Framework provides this. ISA-95 topic hierarchy, MQTT pub/sub, real-time data flow. Your twin's nervous system.
• ✓ A platform to build twin functions — fnkit provides this. Scaffold any function in seconds — quality prediction, vibration analysis, thermal compensation, energy monitoring — whatever your factory needs. Each function connects to the same shared infrastructure.
• ✓ A management layer — GitOps provides this. Version control, code review, safe rollbacks, multi-site consistency, regulatory compliance. Your twin's governance.

Together, these three layers give you a digital twin that is:

Next Steps