115 lines
2.7 KiB
Markdown
115 lines
2.7 KiB
Markdown
|
# 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.
|