Technical architecture

A typed path from signal to an explained outcome.

SkyTwin is a TypeScript monorepo. Its core contract is not “model says do something”; it is a typed candidate action passed through explicit policy, routing, recording, and feedback boundaries.

Implementation source: this guide is a human-oriented map of the technical specification. The repository is authoritative when a detail differs.

Decision pipeline

Ingest a signal. Connectors and local sources provide an event with authoring tier and provenance; source text is not automatically trusted as an instruction.
Build decision context. The system combines the event with the twin profile, preferences, memories, confidence, temporal context, and active policies.
Generate candidates. Each CandidateAction has a risk assessment, cost estimate, reversibility classification, and provenance. Candidate generation cannot assign itself trusted provenance.
Evaluate policy. Trust tier, domain policy, spend limits, injection guard, pause state, risk, and approval rules decide whether the candidate is denied, escalated, or admissible.
Route or stop. An admitted outcome may be routed through an execution adapter; an approval-required outcome waits for a human; an unavailable or denied outcome is recorded as a non-action.
Explain and learn. Supported outcomes persist an explanation record. Approval, rejection, edit, and undo feedback are inputs to the twin model.

Major components

Component	Responsibility	Important boundary
Shared types	Canonical decision, policy, risk, provenance, and workflow interfaces.	Other packages must use these contracts rather than ad-hoc decision or workflow shapes.
Decision engine	Interpret situations, generate and choose candidates.	It produces candidates; it does not grant permission to execute them.
Policy engine	Trust, domain, spend, provenance, injection, pause, and approval evaluation.	Every action must pass it; missing safety inputs fail safe.
Adaptive workflows	Author, validate, replay, activate, revise, and roll back immutable typed workflow versions.	The model may propose structured content; deterministic code owns compilation, hashing, persistence, scheduling, evidence, and authority. Current `signal_digest.v1` runs are read-only.
Execution router	Selects admitted IronClaw, OpenClaw, or direct adapter paths.	Applies a backstop; it does not silently turn an unavailable route into another one.
Memory	Backend-agnostic retrieval with SkyTwin's CRDB-backed gbrain-compatible implementation as default.	Upstream gbrain's CLI is interoperability-only and never runtime-selected; retrieval does not turn remembered text into authority.
LLM client	Explicit provider chain: hosted, Ollama, embedded local runtime, or admitted TrustedRouter.	Provider selection and network boundary are explicit; local or verified-private failure is not a fallback to another boundary.
DB and worker	CockroachDB source of truth plus asynchronous job processing.	Mutations use repository boundaries and serializable transactions where required.

Useful API contracts

Most routes are local API routes. Exact authorization and request/response shapes are in the source specification.

Purpose	Routes	Notes
Fictional sample	`GET /api/v1/demo/info` `POST /api/v1/demo/session`	Separate fixed synthetic principal; read-only allowlist. It is not a user session and does not unlock settings, credentials, execution, or arbitrary reads.
Decisions and approval	`GET /api/decisions/:userId` `GET /api/approvals/:userId/pending` `POST /api/approvals/:requestId/respond`	Use explanation and approval paths to inspect why a decision stopped or waited.
Versioned workflows	`GET /api/adaptive-workflows/:userId/readiness` `POST /api/adaptive-workflows/:userId/signal-digest-drafts` `POST /api/adaptive-workflows/:userId/:workflowId/revisions` `POST /api/adaptive-workflows/:userId/:workflowId/activate` `POST /api/adaptive-workflows/:userId/:workflowId/rollback`	Authoring includes replay and never activates implicitly. Runs pin the exact immutable version, compiled payload, evidence commitment, and inference identity or explicit no-inference state.
Policy and autonomy	`GET /api/policies/:userId` `PUT /api/settings/:userId/autonomy` `PUT /api/users/:userId/autonomy-pause`	Autonomy and pause are explicit control surfaces, not client-side hints.
Health and metrics	`GET /api/health/live` `GET /api/health/ready` `GET /metrics`	See operations for probe semantics and monitoring.

Storage, workers, and failure behavior

CockroachDB is the source of truth for profiles, policy state, decisions, approvals, explanations, feedback, supported account data, workflows, immutable versions, proposals, activation history, scheduler/run pins, and the active Watch projection. Profile mutations are versioned. A claimed workflow slot pins the exact version and compiled payload so a later edit cannot change what that run means. Background work is handled by the worker process; adapters use bounded retries and circuit breakers. Expected operational failure is represented with typed result objects where possible, rather than turning routine absence into an unhandled exception.

What this does not mean

“Stored locally” does not mean every field is application-level encrypted at rest, nor does the existence of an inference receipt make every provider call confidential. Review inference/privacy and privacy before adding sensitive data.

Development quickstart

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm dev

With the normal local development setup, the API is on localhost:3100 and the dashboard is on localhost:3200. For migrations and seed data, use pnpm db:migrate and pnpm db:seed. See the engineering guide for build-cache and parallel-build cautions, and the full specification for the package graph and schema model.