Glossary
The same word means different things in different repositories on this platform. This page is the reconciliation. Where a term is contested, that is stated explicitly.
Platform structure
Section titled “Platform structure”Display tier — demostatics-web. The user-facing web application that shows
information gathered and processed elsewhere, and hosts the community forum. Its README
states the boundary: this repository does not gather or process anything. In practice it
is also the only implemented server and the only identity authority.
Worker tier (also worker backend, worker-pc) — The data-gathering and processing
backend that every repository’s documentation depends on. It exists in no repository.
demostatics-backend is a two-line README. See Worker Tier.
Worker node — An ML model or LLM running as an autonomous distributed unit that pulls tasks from a central server, executes them, and returns processed results. Also the unit of horizontal scaling. Planned.
Detector layer (Algılayıcı katman in the Turkish specification — the same term, not a different one) — The interface
between server and workers: listens for incoming tasks, filters them by worker or group
identity, and routes them into execution queues. Planned.
Thick client — The desktop client’s defining decision: the server supplies data, authentication and entitlements only, and the user interface plus all statistical and mathematical analysis run locally on the user’s machine.
Data and classification
Section titled “Data and classification”Dimensions — Two unrelated meanings. Be careful.
| Context | Meaning |
|---|---|
demostatics-web and the mobile app | The seven nullable filter columns on reports and database_items: region_id, subregion_id, country_id, state_id, city_id, category_id, subcategory_id |
| The founding specification | The five meta-descriptive dimensions every processed output is normalized against: time, capital, workforce, material–energy, information |
The five-dimension model is explicitly superseded by the taxonomy. The seven columns are what actually exists in the schema.
Taxonomy — The desktop client’s server-defined category catalog, delivered in the
Welcome frame: a flat list of {id, label, parent, facet} nodes forming one or more
trees, optionally grouped into named facets. A dataset may belong to several nodes at once.
It exists in Rust only and has no counterpart in Laravel.
Indicator — One measurable series, identified by a string such as gdp_growth.
Desktop vocabulary.
MetricTick — The desktop’s numeric data unit on the wire:
{ indicator, categories: [CategoryId], value: f64 }. Its Laravel counterpart,
database_items.value, is a text column holding a display string such as 48,210 MW.
Report — A worker-produced summary row: title, summary, seven dimension ids, and a
nullable published_at. Filterable and exportable. Shipped as a surface; the rows have
no producer.
Database item — A worker-produced current value: title, value, summary, the same
seven dimension ids, and measured_at defining what “latest” means.
Dimension id 0 — A submitted value of 0 on any dimension filter means unset,
not “id zero”. The dropdown placeholder submits 0.
World geo store — The dr5hn countries-states-cities
dataset, read through
schema-qualified table names (world.regions, world.countries, …) on the same
connection as the rest of the app. There is no separate world Laravel connection.
NULLs-last ordering — Both worker tables sort with a portable
CASE WHEN <col> IS NULL THEN 1 ELSE 0 END expression before the descending sort, because
PostgreSQL otherwise places NULLs first on DESC.
Identity and access
Section titled “Identity and access”Access tiers — Three levels on /api/v1: public (no token), auth (a valid
Sanctum token and not banned), verified (the above plus a verified email address).
Every write, plus Reports and Database, sits in verified.
The three 403s — A 403 from /api/v1 can mean three different things, and a client
must tell them apart: a ban (banned: true plus ban_reason), an unverified email
(email_unverified: true), or an ordinary permission denial (neither flag). Branch on the
flags, never on the bare status.
Token ability — The Sanctum ability vocabulary in App\Support\TokenAbility:
data:read, forum:write, account:write, moderate, ingest:write. Interactive device
tokens are minted with a bounded set rather than Sanctum’s default *, and ingest:write
is deliberately withheld from anything a person signs in with.
Tier — Subscription level. The desktop’s ordered enum:
free < individual < pro < enterprise. It exists only in Rust; the server of record
has no tier column.
Feature — A gate-able capability in the desktop’s entitlement model. Nine kebab-case
wire names: dashboards, risk-views, premium-risk, map-overlays, forums,
reports, api-access, ai-assistant, distributed-compute. The set is open — an
unrecognized name deserializes to Unknown and is never granted, so a newer server cannot
brick an already-shipped desktop.
Entitlements — { tier, features[], allowed_topics[] }, issued by the server in the
Welcome frame. The server is the authority; the client only mirrors it for UI gating.
Usage meters — { meters: [{ name, used, limit, unit }], period_end }, where
limit: 0 means unlimited. The server computes billing; the client only displays how much
is left. No server computes it.
Presence — A user counts as online for presence_ttl seconds (default 300) after their
last request. Any authenticated request, web or API, refreshes it.
Authorized Services — The staff roster panel: admins, technical staff, editors and moderators, plus a live online count. Shipped.
Protocol
Section titled “Protocol”Topic — A structured subscription string on the desktop’s stream: global,
category.<id>, indicator.<id>, or region.<code> (reserved). The server streams a
metric only if it matches a subscribed topic and that topic is inside allowed_topics.
Envelope — Every server-to-client message on the stream:
{ schema_ver, seq, ts, topic, frame }. A frame with an unsupported schema_ver is
dropped outright.
seq / gap / resync — seq is a monotonic per-connection counter. A gap means missed
frames, which triggers a fresh subscribe and a new Snapshot baseline. A Snapshot adopts
its own seq without gap accounting, so detection stays correct across reconnects.
Conflation — The “may drop, never stall” policy. After a frame arrives the data plane drains everything queued behind it and folds it all in before publishing one UI snapshot, so a burst becomes a single update.
Snapshot / Delta — A full baseline on subscribe, then only what changed.
Desktop internals
Section titled “Desktop internals”FeatureModule — The tier-gated mount seam. A pane implements the trait, registers in a registry, and is filtered against its required feature. Nine singleton panes mount this way. Chart and Settings deliberately do not: Chart is multi-instance and Settings edits app-global config the shell reads every frame.
LTTB — Largest-Triangle-Three-Buckets downsampling. Reduces a high-frequency series to the render tier’s point cap while preserving visual shape.
Composite risk — The Risk pane’s pipeline: per-dataset volatility (coefficient of variation), aggregated by top-level taxonomy category, min-max normalized, then weighted-averaged into a 0–100 score and banded.
Render quality / PerfClass — Hardware-profiled graphics tiering. The machine is classified, and the resulting tier sets target frame rate, chart point cap and line width. This tiering is also the documented seam a future GPU paint path consumes unchanged.
Community
Section titled “Community”Community — A forum bucket. Both posts and polls belong to exactly one.
Moderation Board — The governance body composed of editors, moderators and technical staff, whose members are described as being invited through a community-driven nomination process. The roles are Shipped; the nomination process is not.
can block — Per-resource permission flags (can.update, can.delete) computed
server-side from the same policies the web UI uses, so a client renders affordances without
reimplementing permission rules. Always present, and all-false for guests.
Contested terms
Section titled “Contested terms”| Term | Conflict |
|---|---|
| Dimensions | Seven geo/category columns in Laravel, five analytical axes in the founding spec, superseded by the taxonomy in the desktop |
| Forums | Web and mobile share the real forum through the API; the desktop’s Forums pane makes no network calls at all |
| Reports | /reports is worker-produced report listings; /users/{id}/reports is user abuse reports |
| Backend | The founding spec means the C/C++ worker system; demostatics-backend the repository is empty; in practice Laravel is the only backend |
| Task processing system | The English specification calls it a worker-based task processing system; the Turkish one calls it a General Purpose Task Processing System |
- System Map — how the pieces connect
- The Two Contracts — why several of these terms conflict