Mark/easystitch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Decompose: Service documentation (architecture, deployment, performance, development) #40

New issue
Closed
opened 2026-06-22 16:23:20 +00:00 by Mark · 1 comment
Mark commented 2026-06-22 16:23:20 +00:00
Owner
Copy link

Documentation: easyStitch as a service

Context

The README and docs/user_guide.md describe easyStitch as a CLI. The
project is about to be deployed as an HTTP service (issue #31) consumed
by ThreadCraft. No docs cover the service shape, API, deployment, or
operations.

Goal

Add a docs/service.md (or split into multiple docs) covering the
service in its full operational context: architecture, API, deployment,
operations, performance, development.

Decomposition

The original ticket listed 6 sections. They split into 3 shippable
PRs, each ~2 sections.

P1: Architecture overview + API reference

Goal: The "what is this service" doc. New operators should be able
to read this and understand the system shape.

Files:

  • New: docs/service/architecture.md (system diagram, components,
    data flow)
  • New: docs/service/api.md (full endpoint list, request/response
    shapes, error codes, content types, auth model)

Acceptance:

  • docs/service/architecture.md has a Mermaid or ASCII diagram
    showing the service in context (ThreadCraft client → easyStitch
    service → internal pipeline → embroidery file output).
  • docs/service/api.md covers every endpoint from issue #31 (P2–P4)
    with example request/response for each, error codes, content types.
  • Both docs link to the relevant code (src/service/) and to the
    related tickets/issues.

Why first: the API reference is needed by anyone integrating with
the service (including ThreadCraft). Without it, integrations guess at
shapes.

P2: Deployment + operations

Goal: "How do I run this in production." Covers Docker, node_hub,
env vars, log format, healthcheck, monitoring, common failure modes.

Files:

  • New: docs/service/deployment.md (Docker build/run, node_hub
    integration, env vars, port, scaling)
  • New: docs/service/operations.md (log format, /healthz, metrics,
    common errors and what they mean)

Acceptance:

  • docs/service/deployment.md covers: building, running, env vars
    (PORT, MAX_UPLOAD_MB, LOG_LEVEL, WORKER_POOL_SIZE, CORS), port
    (8080), CORS configuration, Docker, node_hub, scaling notes.
  • docs/service/operations.md covers: structured log format, request
    correlation IDs, /healthz semantics, suggested metrics (request
    count, latency histogram, error rate, queue depth), top-5 common
    errors and their fix.
  • A new operator can deploy the service in < 30 minutes reading
    only these two docs.

Depends on: P1 (architecture context).

P3: 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.
# Documentation: easyStitch as a service ## Context The README and `docs/user_guide.md` describe easyStitch as a CLI. The project is about to be deployed as an HTTP service (issue #31) consumed by ThreadCraft. No docs cover the service shape, API, deployment, or operations. ## Goal Add a `docs/service.md` (or split into multiple docs) covering the service in its full operational context: architecture, API, deployment, operations, performance, development. ## Decomposition The original ticket listed 6 sections. They split into 3 shippable PRs, each ~2 sections. ### P1: Architecture overview + API reference **Goal:** The "what is this service" doc. New operators should be able to read this and understand the system shape. **Files:** - New: `docs/service/architecture.md` (system diagram, components, data flow) - New: `docs/service/api.md` (full endpoint list, request/response shapes, error codes, content types, auth model) **Acceptance:** - `docs/service/architecture.md` has a Mermaid or ASCII diagram showing the service in context (ThreadCraft client → easyStitch service → internal pipeline → embroidery file output). - `docs/service/api.md` covers every endpoint from issue #31 (P2–P4) with example request/response for each, error codes, content types. - Both docs link to the relevant code (`src/service/`) and to the related tickets/issues. **Why first:** the API reference is needed by anyone integrating with the service (including ThreadCraft). Without it, integrations guess at shapes. --- ### P2: Deployment + operations **Goal:** "How do I run this in production." Covers Docker, node_hub, env vars, log format, healthcheck, monitoring, common failure modes. **Files:** - New: `docs/service/deployment.md` (Docker build/run, node_hub integration, env vars, port, scaling) - New: `docs/service/operations.md` (log format, /healthz, metrics, common errors and what they mean) **Acceptance:** - `docs/service/deployment.md` covers: building, running, env vars (PORT, MAX_UPLOAD_MB, LOG_LEVEL, WORKER_POOL_SIZE, CORS), port (8080), CORS configuration, Docker, node_hub, scaling notes. - `docs/service/operations.md` covers: structured log format, request correlation IDs, /healthz semantics, suggested metrics (request count, latency histogram, error rate, queue depth), top-5 common errors and their fix. - A new operator can deploy the service in < 30 minutes reading only these two docs. **Depends on:** P1 (architecture context). --- ### P3: 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.
Mark changed title from Documentation: easyStitch is becoming a service — README/docs don't reflect that to Decompose: Service documentation (architecture, deployment, performance, development) 2026-06-22 16:30:52 +00:00
Mark commented 2026-06-22 16:31:37 +00:00
Author
Owner
Copy link

This issue has been decomposed into the following sub-issues:

# Title Phase Scope
#60 Decompose: Service documentation (architecture, deployment, Goal: The "what is this service" doc. New operators should be able to read t
#61 Decompose: Service documentation (architecture, deployment, Goal: "How do I run this in production." Covers Docker, node_hub, env vars,
#62 Decompose: Service documentation (architecture, deployment, Goal: "What to expect at runtime" and "how to develop against the service."

Each sub-issue has been labeled with triage-approved and is ready for queue routing.

This issue has been decomposed into the following sub-issues: | # | Title | Phase Scope | |---|-------|-------------| | #60 | Decompose: Service documentation (architecture, deployment, | **Goal:** The "what is this service" doc. New operators should be able to read t | | #61 | Decompose: Service documentation (architecture, deployment, | **Goal:** "How do I run this in production." Covers Docker, node_hub, env vars, | | #62 | Decompose: Service documentation (architecture, deployment, | **Goal:** "What to expect at runtime" and "how to develop against the service." | Each sub-issue has been labeled with `triage-approved` and is ready for queue routing.
Mark closed this issue 2026-06-22 16:31:37 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
blocked:children

   
blocked:depends-101

Depends on Mark/easystitch#101 landing first.

  
blocked:depends-103

Depends on corresponding issue landing first.

  
blocked:depends-104

Depends on corresponding issue landing first.

  
blocked:needs-attention

Session stuck or abandoned, needs human review

  
blocked:needs-decision

   
blocked:no-changes

   
blocked:preflight

Held by kilo-gsd preflight until lint-cleanup lands

  
bug

Something is not working correctly

  
chore

Config/cleanup items (reporter lane)

  
feature-request

   
in-progress

Claimed by kilo-gsd pipeline

  
lint-cleanup

Repo-wide lint cleanup ticket — kilo-gsd preflight hard-gate

  
needs-decompose

   
performance

   
quality

   
quickfix

   
security/medium

Medium severity security issue

  
triage-approved

Triage: approved for fixer pipeline

No labels
blocked:children
blocked:depends-101
blocked:depends-103
blocked:depends-104
blocked:needs-attention
blocked:needs-decision
blocked:no-changes
blocked:preflight
bug
chore
feature-request
in-progress
lint-cleanup
needs-decompose
performance
quality
quickfix
security/medium
triage-approved
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Mark/easystitch#40
No description provided.