tinylink/docs/separated_architecture.md

TinyLink Separated Architecture

Why this refactor

TinyLink now separates runtime wiring, host communication, instrument communication, and operational HTTP endpoints. The goal is clearer ownership per module and easier future expansion for instrument-request workflows.

Folder layout

core/
  index.js
  app.js

  host/
    resultClient.js
    resultService.js

  instrument/
    ingest.js
    connectors/
      httpJson.js
      tcp.js
      serial.js

  runtime/
    startup.js
    connectors.js
    workers.js

  workers/
    host/
      resultWorker.js

  http/
    index.js
    healthRouter.js
    metricsRouter.js
    instrumentRouter.js
    dashboardRouter.js
    dashboard/
      page.js

  queue/
    db.js
    queue.js

  config/
    config.js
    instrumentConfig.js
    instrumentCheck.js

  maintenance/
    schema.sql
    migrate.js
    maintenance.js

  pipeline/
    hash.js
    normalizer.js
    pipeline.js
    translator.js

  util/
    logger.js

Responsibilities

• runtime/: startup orchestration only (migrate, config init, start connectors/workers, open HTTP server, graceful shutdown).
• host/: outbound result delivery to host API, including retry/dead-letter decisions.
• instrument/: inbound connector protocol adapters and ingest handoff to pipeline.
• workers/: polling loops and queue claim logic, organized by target domain.
• http/: all API/UI routes.
• queue/: SQLite persistence and query helpers.
• runtime/: startup and graceful shutdown orchestration only.
• pipeline/: translation/normalization/dedupe logic only.
• util/: shared generic helpers.

Runtime flow (result path)

1. Connector receives raw instrument payload.
2. instrument/ingest forwards payload to pipeline/processMessage.
3. Pipeline writes to queue tables (inbox_raw, outbox_result).
4. workers/host/resultWorker claims pending outbox rows.
5. host/resultService sends to CLQMS host and updates status/retry/dead-letter.

Dashboard UI

The built-in dashboard is available at:

• GET /dashboard

Dashboard APIs:

• GET /dashboard/api/summary
• GET /dashboard/api/queue
• GET /dashboard/api/instruments
• GET /dashboard/api/recent

The page auto-refreshes every 5 seconds and shows queue counters, instrument connector state, queue tail, and recent delivery attempts.

Compatibility notes

• core/app.js remains as the entry import and now delegates to core/runtime/startup.js.
• core/http.js remains and delegates to core/http/index.js.

Deferred scope

Instrument request flow (host -> instrument, and query roundtrip) is intentionally deferred. The new structure keeps clear slots for:

• core/instrument/
• core/workers/requestWorker.js

without mixing those concerns into the result-delivery path.