Threadmark

ThreadMark is a review-intelligence application that turns product-review data into ranked, explainable outcome-risk signals for product, merchandising, operations, and customer-experience teams.

The implemented core is a Dual-Lane direct-outcome system. One locally trained, calibrated text model estimates whether a review supports recommendation. A second text model estimates the distribution of likely 1–5 ratings and low-rating risk.

RIK 2.0 is the deterministic analytical layer. In the implemented lane it combines direct recommendation probability and rating-distribution outputs into support-aware group risk, uncertainty, health, priority, queue state, representative evidence, and anomaly results. Te.

The system uses PostgreSQL as both the application database and durable job queue. An analysis request is enqueued through the API, claimed only by an analysis worker with row locking, processed in bounded batches, persisted transactionally with dataset/model lineage, and exposed through job and analysis-run readback endpoints. Docker Compose supplies an API, PostgreSQL, and ML worker deployment suitable for the initial small-team environment without lowering the implementation standard.

Built architecture

flowchart TD
    F[Existing ThreadMark frontend] --> API[Dual-Lane Express API]
    API --> J[(PostgreSQL jobs)]
    API --> READ[Job and analysis-run readback]
    J --> W[Python Dual-Lane worker]
    W --> ART[(Pinned local model artifacts)]
    W --> DB[(PostgreSQL durable outputs)]
    DB --> READ
    W --> RIK[Deterministic direct-outcome RIK 2.0]
    RIK --> DB

Model and data flow

flowchart LR
    C[Clothing reviews with native recommendation] --> TRAIN[Owned training code]
    TRAIN --> REC[Calibrated recommendation artifact]
    TRAIN --> RAT[Target-safe rating-distribution artifact]
    D[Disneyland reviews with rating proxy] --> EVAL[Cross-domain evaluation]
    REC --> INF[Bounded local inference]
    RAT --> INF
    INF --> AGG[Group aggregation]
    AGG --> OUT[RIK, evidence, anomaly, lineage]

Runtime job sequence

sequenceDiagram
    participant UI as Frontend
    participant API as Express API
    participant DB as PostgreSQL
    participant W as Python worker
    participant ML as Local artifacts

    UI->>API: POST /v1/analysis/jobs
    API->>DB: enqueue_job(analysis)
    DB-->>API: job id
    API-->>UI: 202 queued
    W->>DB: claim_next_analysis_job()
    W->>DB: read immutable dataset reviews
    W->>ML: load calibrated artifacts
    ML-->>W: predictions
    W->>W: aggregate direct outcomes and RIK
    W->>DB: persist outputs and lineage
    W->>DB: complete_job()
    UI->>API: GET job/run
    API->>DB: tenant-scoped readback
    DB-->>API: status and results
    API-->>UI: persisted analysis

Engineering approach

Current quality status

The implementation has passed 21 automated Python tests, Node syntax checks, Compose validation, Docker image builds, PostgreSQL migration execution, API health, live queue processing, output persistence, API readback, and wrong-tenant rejection.

Built With

• express.js
• gpt-5.6
• node.js
• pandas
• pgvector
• postgresql
• python
• scikit
• vite