# 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

```text
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.