Technical overview¶

Status: draft

How the next version (0.1) is built – updated for every version. Proposals by Claude, 2026-10-19; nothing on these pages is binding until Daniel approves it. Questions that block work are collected in Open questions.

Goal¶

Build release 0.1 (Roadmap): the CLI with the open file format, the adapters Markdown, rST/Sphinx-Needs and plain text, and the agent skills deciwa-work and deciwa-ask – good enough that Daniel uses deciwa in his knowledge base instead of [CHECK] markers.

Not in 0.1: push / pull, VS Code, Chrome, hosted service, Python/HTML adapters. The design must not block them, though – especially review on results (Reviews happen on results, ... (DEC_REVIEW_ON_RESULTS)).

Repository¶

deciwa/
├── packages/            one package per part – see below
│   ├── core/            deciwa-core     model, .deciwa/ store, engine
│   ├── server/          deciwa-server   review server
│   ├── cli/             deciwa-cli      the deciwa command
│   ├── ui/              deciwa-ui       review overlay (JS/CSS)
│   └── sphinx/          deciwa-sphinx   Sphinx extension
├── docs/                these docs – product, integrations, decisions,
│                        technical details
├── .deciwa/             review data of these docs (config.toml: what must be approved)
├── mockups/             first clickable mock-up of the feedback UI, demo recorder
├── pyproject.toml       the uv workspace (all packages + docs tools)
└── uv.lock

Packages¶

The split into packages is deciwa is one repository of... (DEC_PACKAGES).

deciwa is one repository with one package per part – a uv workspace. All packages share the Python namespace deciwa.

Solid: what a package imports. Dashed: how the parts talk to each other while reviewing with a server.

Folder	Distribution	Import	Contains	Depends on
`packages/core`	`deciwa-core`	`deciwa.core`	model, `.deciwa/` store, engine – states, review rules, project overview, export/import	–
`packages/server`	`deciwa-server`	`deciwa.server`	local review server: serves a built site, the JSON API for the review UI, rebuilds and reloads on change; knows no build tool – the caller passes the build command	core
`packages/cli`	`deciwa-cli`	`deciwa.cli`	the `deciwa` command; `deciwa serve` passes the Sphinx build to the server	core, server
`packages/ui`	`deciwa-ui`	`deciwa.ui`	the review overlay (JavaScript, CSS, logo) in the danwos tool UI kit, including the offline engine; no Python logic	–
`packages/sphinx`	`deciwa-sphinx`	`deciwa.sphinx`	Sphinx extension: finds the elements of every page, writes the elements index, ships the review UI	core, ui

deciwa-sphinx does not import deciwa-server: a static (offline) build needs no server. With deciwa serve, the server runs the Sphinx build, and the review UI in the pages talks to the server’s JSON API.

Rules:

Logic lives in deciwa-core only. The offline engine in deciwa-ui mirrors its rules for reviews without a server and must be kept in step.
deciwa-server and deciwa-cli are reused by every integration that reviews in a browser or calls the CLI.
An integration package depends on deciwa-core and, for a browser UI, on deciwa-ui – never on another integration.

Setting up¶

$ uv sync                          # all packages, editable, plus the docs tools
$ .venv/bin/deciwa serve           # the CLI from packages/cli

Using deciwa in another Sphinx project:

$ cd ~/workspace/deciwa/packages
$ uv pip install --python <project>/.venv/bin/python -e core -e server -e cli -e ui -e sphinx

Pages¶

Page	Decides
Stack	language, packaging, tooling
Layers	modules of the core and how they depend on each other
Adapters	how a format turns into elements and selectors
File format	the JSON inside `.deciwa/`
State engine	how the state of an element is computed
CLI	commands, element addressing, JSON output
Skills	what the two agent skills do and how they ship
Rollout	how 0.1 gets into Daniel’s knowledge base
Working on deciwa	docs as the truth, reviewing them in deciwa, from proposal to decision

All proposals¶

ID	Title	Status	page
PROP_ADAPTER_API	One small adapter interface for all formats	draft	technical/adapters
PROP_ANNOTATION	Annotation structure	draft	technical/file-format
PROP_CLI_CHECK	deciwa status can fail a CI run on freeze alarms	draft	technical/cli
PROP_CLI_COMMANDS	Commands in 0.1	draft	technical/cli
PROP_CLI_JSON	JSON output has one envelope for every command	draft	technical/cli
PROP_FILE_LAYOUT	One annotation file per source, deterministic JSON	draft	technical/file-format
PROP_FINGERPRINT	The fingerprint covers the source text with whitespace normalised	draft	technical/state-engine
PROP_FREE_TEXT	A free text selection is a text quote inside its nearest element	draft	technical/adapters
PROP_LATEST_WINS	While an element is unchanged, an author's latest verdict and latest rating replace the earlier ones	draft	technical/file-format
PROP_LAYERS	The core is split into layers with a strict dependency direction	draft	technical/layers
PROP_PYTHON_CORE	The core and the CLI are written in Python	draft	technical/stack
PROP_RESOLVE	Selectors are tried in a fixed order and the first unique hit wins	draft	technical/state-engine
PROP_ROLLOUT_LOCATION	.deciwa/ at the root of the knowledge base, committed	draft	technical/rollout
PROP_ROLLOUT_MIGRATE	Existing [CHECK] markers are migrated once into requests	draft	technical/rollout
PROP_RST_DOCUTILS	The rST adapter parses with docutils, without running Sphinx	draft	technical/adapters
PROP_SCHEMA	A JSON Schema is the documented contract	draft	technical/file-format
PROP_SELECTORS	Element selectors are paths of headings plus a per-section counter	draft	technical/adapters
PROP_SKILLS_FORMAT	Two skills in the Agent Skills format, shipped in the repository	draft	technical/skills
PROP_SNAPSHOT	The snapshot of the element text is stored with every annotation	draft	technical/file-format
PROP_STATE_RULES	State rules in this order	draft	technical/state-engine
PROP_TOOLING	Tooling: Python 3.12+, uv, ruff, pytest, click	draft	technical/stack

How the proposals relate to the decisions¶