Decompose: Service documentation (architecture, deployment, performance, development) — Phase 3: Performance + development workflow #62

New issue

Closed

opened 2026-06-22 16:31:36 +00:00 by Mark · 0 comments

Mark commented

2026-06-22 16:31:36 +00:00

Owner

Phase 3: Performance + development workflow

Goal: "What to expect at runtime" and "how to develop against the
service." These are the docs the maintainer and the integrator need
when things get weird.

Files:

New: docs/service/performance.md (typical latencies, max input
sizes, recommended CPU/RAM, throughput expectations, regression
detection)
New: docs/service/development.md (local dev setup, running
tests, hot-reload, integration testing against the ThreadCraft
client)

Acceptance:

docs/service/performance.md includes observed numbers from real
runs (not theoretical), with the hardware spec, and a regression
detection strategy (e.g. "alert if p99 digitize latency > 5s for
7 days").
docs/service/development.md covers: make dev or equivalent
workflow, running pytest, running the service against a local
ThreadCraft dev instance, hot-reload setup, common dev pitfalls
(the relative-imports bug, the defusedxml migration, the
requirements.txt venv gap — all of which are issues on this
repo).
Both docs include a "Last updated" date.

Depends on: P1, P2 (operational context).

Out of scope

The existing CLI docs (docs/user_guide.md, docs/installation_and_usage.md)
are unchanged. They describe the CLI path; the new docs/service/
describes the service path. The README links to both.
Tutorial / quickstart for new easyStitch users. Different doc, different
audience; out of scope for the service docs.

Decomposed from easystitch#40

## Phase 3: Performance + development workflow **Goal:** "What to expect at runtime" and "how to develop against the service." These are the docs the maintainer and the integrator need when things get weird. **Files:** - New: `docs/service/performance.md` (typical latencies, max input sizes, recommended CPU/RAM, throughput expectations, regression detection) - New: `docs/service/development.md` (local dev setup, running tests, hot-reload, integration testing against the ThreadCraft client) **Acceptance:** - `docs/service/performance.md` includes observed numbers from real runs (not theoretical), with the hardware spec, and a regression detection strategy (e.g. "alert if p99 digitize latency > 5s for 7 days"). - `docs/service/development.md` covers: `make dev` or equivalent workflow, running pytest, running the service against a local ThreadCraft dev instance, hot-reload setup, common dev pitfalls (the relative-imports bug, the defusedxml migration, the requirements.txt venv gap — all of which are issues on this repo). - Both docs include a "Last updated" date. **Depends on:** P1, P2 (operational context). ## Out of scope - The existing CLI docs (`docs/user_guide.md`, `docs/installation_and_usage.md`) are unchanged. They describe the CLI path; the new `docs/service/` describes the service path. The README links to both. - Tutorial / quickstart for new easyStitch users. Different doc, different audience; out of scope for the service docs. --- _Decomposed from [easystitch#40](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/40)_