---
title: PostgreSQL + TimescaleDB
type: entity
created: 2026-04-30
updated: 2026-05-01
sources: [gps-tracking-architecture]
tags: [infrastructure, business-plane, database]
---

# PostgreSQL + TimescaleDB

The durable storage layer. PostgreSQL with the TimescaleDB extension. Holds the positions hypertable and all business schema owned by [[directus]].

## Writers

- **[[processor]]** — sole writer for high-volume telemetry (positions hypertable) and writer for derived business entities (events, violations, alerts).
- **[[directus]]** — writes from the admin UI, custom endpoints, and Flows. Owns schema definition and migrations.

[[react-spa]] never writes (or reads) directly. [[tcp-ingestion]] does not touch the database.

## Schema authority

Schema is **defined and migrated through [[directus]]** — see that page for why. The Processor inserts rows respecting that schema; it does not create tables.

## Positions hypertable

Stores normalized [[position-record]] rows from [[processor]]. Beyond the wire-shape fields (device_id, timestamp, lat/lon/alt, angle, speed, satellites, priority, attributes), the hypertable carries one storage-only field:

- **`faulty boolean DEFAULT false`** — set by track operators via [[directus]] when a position is unrealistic (jumpy GPS, impossible speed/coordinate). The [[processor]]'s evaluators (peak-speed, crossing detection, recompute) filter `WHERE faulty = false` on every read of position data. Untouched at write time; mutated only through the operator workflow described in the schema draft.

## Operational note

The database is the **only single point of failure** in the architecture. Everything else is restartable, replaceable, or naturally redundant. Operational attention concentrates here:

- Replication
- Backups
- Point-in-time recovery via TimescaleDB

## Scaling

- **Vertical** for write throughput.
- **Read replicas** for analytics workloads.

## Deployment

Internal-only container. Persistence volume. Regular backups. Accessed only by [[directus]] and [[processor]].