Architecture
This document describes how Kinenix is structured: its principles, modules, execution pipeline, AI integration, and the planned distributed architecture. It separates what exists today from the target design. For delivery status and priorities, see roadmap.md.
1. Core Principles
- Local AI-Native: Designed for on-device Small Language Models (SLMs) running on CPU (e.g. Qwen 2.5, Llama 3.2 via Ollama, llama.cpp, or ONNX). AI powers extraction and decision steps in flows with no cloud token costs and no business data leaving the network.
- Deterministic first, agentic second: Flows execute deterministically step by step. AI is used inside explicit actions (
ai.*) or as an observer, never as a hidden replacement for flow logic. - Zero-license Office dependency: Spreadsheet processing uses file-level libraries (
openpyxl,pandas). Microsoft Excel or Microsoft 365 is never required. - Business-first telemetry: Logs and dashboards report business outcomes (transactions, hours saved, cost saved), not only stack traces.
- Free, unlimited workers: No per-bot licensing. Workers run on any PC, VM, or edge device such as a Raspberry Pi.
- Flows as code: A flow is a Markdown file (
flow.md) versioned in Git. A deployed package (.kinx) is a signed zip of the same files, not an opaque binary. - Extensible in Python: New actions are Python classes registered with the action registry.
2. Modules
| Module | Role | Current implementation | Target |
|---|---|---|---|
kinenix-core | Flow interpreter, variable evaluator, action plugins, kinenix CLI | Python 3.12+, Pydantic, Playwright, openpyxl, pandas | Same |
kinenix-worker | Runs flows unattended on target machines | CLI with run, watch, schedule, daemon; optional separate copy of the bundle per run (--sandbox, not isolation) | Long-poll client that receives confirmed jobs and signed flow packages from the Hub (1.5.0) |
kinenix-studio | Flow authoring and debugging | FastAPI backend + React/Vite web UI: flow discovery, editing, validation, run | Tauri desktop shell, persistent browser sessions, element picker, live debugger |
kinenix-hub | Central monitoring and control | FastAPI + SQLAlchemy (SQLite default); receives heartbeats and telemetry over HTTP; web dashboard; API key auth | Job dispatch and flow delivery over long polling (1.5.0), PostgreSQL, ROI dashboard |
Current Data Flow
graph LR
Studio["kinenix-studio<br>(edit / run flows)"] -->|reads and writes| Flows["flows/ bundles"]
Worker["kinenix-worker<br>(run / watch / schedule)"] -->|executes| Core["kinenix-core<br>interpreter"]
CLI["kinenix CLI"] -->|executes| Core
Core -->|reads| Flows
Core <-->|HTTP| AI["Local AI<br>(Ollama / SystemOne)"]
Core -->|JSON logs| Logs["logs/"]
Core -->|HTTP telemetry + X-API-Key| Orch["kinenix-hub"] Target Architecture
graph TD
Build["Building machine<br>kinenix pack signs a .kinx package"] -->|kinenix publish| Hub["Kinenix Hub<br>Packages, confirmed jobs, run records"]
Worker["Kinenix Worker<br>Daemon on VM / PC / edge device"] -->|Long poll: jobs and packages| Hub
Worker -->|Execute flow| Core["Kinenix Core<br>Interpreter engine"]
Core <-->|HTTP REST / JSON| AI["Local SLM sidecar<br>Ollama / llama.cpp"]
Worker -->|Telemetry and heartbeats| Hub
Agent["AI agents such as kytnix"] -->|Read-only queries| Hub 3. Execution Pipeline (kinenix-core)
sequenceDiagram
autonumber
participant CLI as CLI / Worker
participant Engine as Flow Interpreter
participant Context as Execution Context
participant Registry as Action Registry
participant Target as External Target (Web / Excel / AI)
participant Log as Structured JSON Log
CLI->>Engine: Load flow.md and config.json
Engine->>Context: Initialize variables (${config.*}, ${env.*}, --vars)
loop Each step
Engine->>Context: Evaluate expressions (${var.prop})
Engine->>Registry: Look up action class (e.g. "web.open")
Registry-->>Engine: BaseAction subclass
Engine->>Target: execute(parameters, context)
Target-->>Engine: Result or exception
alt Success
Engine->>Context: Store result in output_var
else Failure
Engine->>Engine: Apply on_error (fail / continue / next_item)
Engine->>Target: Capture failure screenshot if a browser page is open
end
end
Engine->>Log: Write logs/<flow>/<date>/<HHMMSS>_<status>.json
Engine-->>CLI: Final status Key implementation files: - Interpreter, error handling, retry and fallback: kinenix-core/kinenix/engine/interpreter.py - Expression evaluation (no eval): kinenix-core/kinenix/engine/evaluator.py - flow.md compiler: kinenix-core/kinenix/engine/markdown.py (spec: flow_markdown_spec.md) - Log writer and telemetry upload: kinenix-core/kinenix/engine/logger.py (format: logging.md)
Flows are organized as self-contained project bundles; see project_bundles.md.
4. AI Integration
AI runs as a decoupled sidecar, only in flow actions. The Hub calls no model: the cause and fix of a failure are written by the worker's own rules (engine/action_errors.py, engine/web_errors.py), and agents such as kytnix read them from the Hub. kinenix-core stays lightweight and can run every non-AI flow without any ML runtime installed.
| Where | What it does | Implementation |
|---|---|---|
| Flow actions | ai.prompt (JSON-constrained prompts), ai.extract (structured fields from text or images), ai.decide | Ollama and OpenThai-SystemOne over HTTP (kinenix-core/kinenix/actions/ai_*.py) |
See actions_reference.md for action parameters and rpa-challenge-ocr in kinenix/examples for an end-to-end example.
Planned: self-healing selectors, a Studio copilot for natural-language flow authoring, and SLM diagnosis sent to LINE notifications.
5. Hub and Worker Communication
Today: workers push telemetry and heartbeats to the Hub over HTTP (POST /api/v1/telemetry) with the worker key; see hub.md. A run record carries both machine fields (status, counts, error codes) and a Markdown report (report_md in v_runs) that people and AI agents read.
Planned for 1.5.0 (decided 2026-11-12 and 2026-11-14, replacing a WebSocket protocol planned before): the worker keeps one long-poll request open to the Hub (GET /api/v1/jobs/next), so it opens no port. The answer is a job a person confirmed on the dashboard, for a flow already on the worker that its owner allowed, or a signed flow package to install. Workers report runs as today. Details: design/agent-interface.md, section 14, and design/flow-deploy.md.
6. GitOps Deployment (Planned)
- Author: Build and tune flows locally with the CLI or
kinenix-studio. - Version: Commit
flow.md,subflows/,config/, and assets to Git. - Validate: CI runs
pytestand flow schema validation on every pull request. - Release:
kinenix packbuilds a signed.kinxpackage of a version, and workers install it from a file or, from 1.5.0, from the Hub (design/flow-deploy.md).
7. Repository Layout
Kinenix/
├── kinenix-core/ # Runtime engine and CLI (kinenix)
│ ├── kinenix/
│ │ ├── actions/ # Web, Excel/CSV, file, HTTP, email, logic, flow, AI actions
│ │ ├── engine/ # Interpreter, evaluator, flow.md compiler, logger
│ │ └── models/ # Pydantic flow and context models
│ └── tests/
├── kinenix-worker/ # Unattended runner and triggers (kinenix-worker)
├── kinenix-studio/ # FastAPI backend (kinenix-studio) + frontend/ (React/Vite)
├── kinenix-hub/ # Central telemetry server and dashboard
├── flows/ # Project bundles; @shared/ holds reusable subflows
├── schemas/ # JSON schemas for flows and execution logs
├── docs/ # Documentation (index: docs/README.md)
├── logs/ # Execution logs (git-ignored)
├── .agents/rules/ # Engineering rules for AI assistants
└── AGENTS.md # Entry point for AI assistants