Skip to content

Version Control

🧠 Philosophy

As data scientists and AI engineers, we’ve long felt the pain of working with no-code or low-code platforms that lack proper version control. While visual builders can speed up experimentation, they often hide complexity and make it difficult to:

  • Track changes across iterations
  • Revert or branch logic
  • Collaborate with others confidently

That’s why INTELLITHING is designed as a configuration-based platform — even if you build visually, the true source of truth is a set of JSON configuration files that define your workflow, models, routing, and environment.

This foundational decision makes it natural to support real Git version control — not a watered-down substitute. The UI is just a builder; under the hood, it’s code.

🔑 Key Concepts

INTELLITHING treats every project as a Git-backed repository of configuration blueprints:

  • Blueprints: JSON files that define workflows, models, routes, environment, and deployment settings.
  • Git branches: Your development flows follow Git conventions (main, feature branches, forks, pull requests).
  • Commit view: Track and describe changes before finalizing them.
  • Diff view: Visualize what's changed between your working files and committed history.
  • Forking: Clone a branch to test configuration changes without affecting others.

This means you can:

  • Build visually, commit structurally
  • Use branches for safe iteration
  • Review changes like a developer
  • Revert mistakes with ease

📘 Key Definitions

Term Description
Main Branch The default, stable branch. Avoid direct commits.
Feature Branch A branch created for new features, experiments, or fixes.
Pull Request A proposal to merge your changes back into main or another branch.
Fork A temporary branch used for testing uncommitted changes at runtime.
Diff View A visual comparison of your pending changes vs. the last commit.
Commit Changes Finalizing your edits with a message and saving them to the current branch.

🧩 Versioning at a Glance

One-line Summary

Workflow = { JSON configs } → Git-controlled → UI-rendered

Visual Flow

  1. Edit config files (via UI or JSON)
  2. Review changes in the Diff tab
  3. Commit changes to a Git branch
  4. Create pull request if ready to merge
  5. Fork to test changes in isolation

⚙️ How Version Control Fits into INTELLITHING

Version control in INTELLITHING is not an add-on — it is baked into how workflows are authored, tested, and deployed.

  • Everything you build — blocks, bridges, routes, models — is saved as JSON blueprints.
  • These blueprints live in a Git repository.
  • Each branch maps to a versioned configuration state.
  • The UI reflects your current Git state — editing is just another way to change the underlying JSON.

You are free to use the UI — but everything under the hood is reproducible, versioned code.

🧬 Supported Configuration Files

INTELLITHING accepts the following file types (in JSON):

File Name Required Purpose
data.json ✅ Core block logic, credentials, and wiring
routers.json ✅ Routing logic and bridge definitions (can be empty {})
llm.json ✅ Large language model settings (e.g. provider, params)
tml.json ❌ Traditional ML model config and I/O mappings
deployment.json ❌ Deployment-specific resources (CPU/GPU/memory)
env_var.json ❌ Runtime environment variables (e.g. secrets, URLs)

🔐 Viewing configs in Code View requires elevated permission (included in owner, admin, and moderator roles by default).

📤 Commit Workflow

  1. Start on main (or another stable branch).
  2. Create a new branch for your changes.
  3. Edit via UI or upload JSON configs.
  4. View the Diff tab to compare uncommitted changes.
  5. Write a descriptive commit message.
  6. Click Commit Changes.

💡 Avoid committing directly to main. Use Git best practices: branch → commit → pull request → merge.

🔀 Pull Requests & Forking

Feature Description
Pull Request Merge changes from your branch into another (e.g. main) with review visibility
Fork Create a temporary copy of your branch for live testing without merging

This allows for safer development and collaborative workflows. Forking is especially useful when you want to test runtime behavior before committing changes.

📊 Diff View

Before committing, always check the Diff tab:

  • Compare your current workspace vs. the last commit.
  • See what blocks, models, routes, or settings changed.
  • Confirm nothing accidental is about to be saved.

Think of it like git diff — but made visual and workflow-aware.

🧭 Best Practices

Practice Why it matters
Don’t commit to main Keeps the main branch clean and deployable
Use PRs and Forks Collaborate, test, and validate before merging
Commit in small units Easier to debug, track, and revert changes
Write clear commit messages Helps others (and your future self) understand what changed
Always check the Diff tab Prevents accidental config overwrites or unwanted deletions

🔐 Permissions

Feature Required Role/Permission
View Code admin, owner, or moderator
Commit Changes Any user with branch access
Fork/PR All users in a project

Admins can manage permissions via the workspace settings.

💬 Summary

  • Version control in INTELLITHING is powered by real Git.
  • Your workflows are JSON blueprints, not opaque UI state.
  • You can use the UI, but Git is always behind the scenes.
  • Branch, edit, diff, commit, and pull request — just like any codebase.
  • All of this happens natively inside INTELLITHING — no extra setup required.