Architecture

DRAKULIS has one runtime and three deployment shapes. The original native CLI executes locally with SQLite and a loopback model. Studio submits work to an authenticated control-plane API. A separate worker executes the same runtime over an authenticated HTTP contract; it does not import the API application, read its memory, or connect to its database.

Studio -> reverse proxy -> API -> SQLite or PostgreSQL durable queue
                              ^
                              | authenticated, fenced HTTP reports
                         independent worker -> local model
                              |
                         approved read tools

The API stores conversations, task payloads, status, traces, text artifacts and approval decisions. No model inference or tool execution occurs in API request handlers. Read-only health is public; data routes require the operator token, and worker routes require a distinct worker token. This version is a single trusted operator deployment, not a multi-tenant service.

The durable database queue replaces a separate Redis dependency. A claim includes a versioned payload and a unique fencing token. A 30-second lease is refreshed during execution. Every progress, message, state and approval write validates the lease transactionally. Expired work is eligible for another worker up to three attempts. Cancellation revokes the lease immediately. Read-only tools may be replayed after a crash; arbitrary side-effecting tools remain unavailable.

Version 1 payloads carry conversation ID, prompt, model and immutable artifact IDs. UTF-8 text artifacts are stored explicitly in the control-plane database and transferred only to the claimed worker. The worker stages them in a task-local temporary directory. Without uploaded artifacts, a worker can use its own explicitly configured workspace. Worker extraction therefore does not require shared host paths. A future blob-store backend can replace small database artifacts without changing the runtime contract.

Local mode remains independent of hosted DRAKULIS services. Local dependency/model provisioning needs network access initially; after provisioning, the CLI and local dashboard stack use only local processes. The default gateway permits only loopback URLs, disables environment proxy inheritance and redirects, and never falls back to cloud providers. Compose runs worker/model traffic on an internal network and disables Ollama cloud features.

Schema: SQLAlchemy-backed SQLite or PostgreSQL with Alembic baseline migration. Existing Sprint 1 SQLite rows are retained. Automatic initial table creation remains for native first run; production upgrades use an explicit single-administrator migration step. Future structural changes require new migrations.

Both OpenAI-compatible SSE and optional native Ollama NDJSON are normalized into the same runtime message/event format. Native protocol selection is explicit via DRAKULIS_MODEL_PROTOCOL=ollama; it is not an automatic fallback. Empty or truncated model responses fail closed. Native usage events record input/output token counts when the server supplies them. Tool-choice hints are provider-dependent and do not bypass permissions.

V4 intelligence slice

The model is a replaceable reasoning component. The runtime now uses the provider-neutral ReasoningModel contract, injects manual model selection through the component's for_model interface, and applies locality/privacy policy before sending context. It no longer imports or constructs a concrete gateway. Optional native Anthropic/Gemini codecs sit at the boundary, not in the agent loop. Their live service qualification is pending; no cloud credentials were used in tests.

A task records its workflow, declared success criteria and bounded recovery strategy before execution. The deterministic verification engine consumes actual current-task tool evidence. Completion without criteria is marked unverified; unmet criteria terminate as verification_failed. At most one explicitly configured recovery can request corrective reasoning within the existing execution budget. No extra planner/reviewer model calls are required for simple tasks.

A bounded execution context defines future specialized roles and delegation budgets; it does not enable speculative multi-agent scheduling. Approved preferences, reusable knowledge correction/deletion, learned procedures and semantic retrieval remain subsequent work. Existing conversation/task storage is retained.

Task contract v2 adds privacy and verification requirements. Current workers accept v1/v2, but v2 work is not delivered to a worker advertising only v1. This avoids old workers silently ignoring new privacy/evidence policies. The legacy CLI and v1 persisted tasks remain supported.