Terragnos Core Overview

Terragnos Core packages a ready-to-run spatial object store, workflow engine, and automation runtime that ships as container images. This page focuses on how to run those images, what capabilities they expose to developers, and where the platform is heading—without diving into internal repository details.

Containerized setup

Images and responsibilities

Image	Purpose	Defaults	Required configuration
terragnos-core-db (PostGIS 16)	Stores all objects, workflow state, relations, and audit records.	Port 5432. Persistent volume terragnos-db-data.	POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD.
terragnos-core-db-setup	Runs database migrations and seeds a demo tenant.	Runs once, exits when migrations succeed.	DATABASE_URL that points at the database container.
terragnos-core-api	Serves the REST/GraphQL surface (/v1/...), OpenAPI, webhook ingress, and admin endpoints.	Port 3000.	DATABASE_URL, AUTH_JWT_SECRET, optional AUTH_DEFAULT_TENANT, LICENSE_*, caching/throttling env vars.
terragnos-core-worker	Processes outbox deliveries, workflow transitions, automation rules, and background jobs.	No public port. Shares the same .env values as the API.	DATABASE_URL, LICENSE_*, any feature flags (Redis, rate limits, etc.).

Image tags follow product releases (for example v0.4.0). Always run the API and worker on the same tag so database migrations and feature flags stay aligned.

Important: While Terragnos Core provides a terragnos-core-db image for convenience, you can use your own PostgreSQL + PostGIS database. Simply point the DATABASE_URL environment variable to your existing database instance. The system only requires:

• PostgreSQL 15+ with PostGIS 3.4+ extension
• Extensions: postgis, pgcrypto, uuid-ossp, pg_trgm
• A database user with sufficient privileges to create schemas and run migrations

The db-setup container (or manual migration scripts) will handle schema initialization regardless of whether you use the provided image or your own database.

Quick start with Docker Compose

# 1. Make the runtime configuration available to Compose.
cat <<'EOF' > .env
DATABASE_URL=postgres://terragnos:terragnos@db:5432/terragnos
AUTH_JWT_SECRET=change-me
AUTH_DEFAULT_TENANT=default
LICENSE_PUBLIC_KEY=./license-public.pem   # optional
LICENSE_KEY=                               # optional
REDIS_URL=                                 # optional
EOF

# 2. Start PostGIS and run migrations/seeds once.
docker compose up -d db
docker compose --profile setup up db-setup && docker compose --profile setup down

# 3. Launch the runtime containers.
docker compose up -d api worker

# 4. Verify the stack.
curl http://localhost:3000/v1/health/live

Helpful environment switches:

• AUTH_DISABLED=true lets you smoke-test the platform without JWT validation (do not use in production).
• RATE_LIMIT_TTL and RATE_LIMIT_LIMIT cap incoming requests globally.
• LAYER_CACHE_TTL_SECONDS configures how long GeoJSON/mvt responses stay cached.
• LICENSE_STORAGE_SECRET encrypts the installed license at rest inside the database.

To upgrade:

1. Pull the new images: docker compose pull api worker (the database image only changes when PostGIS is updated).
2. Rerun migrations if the release notes mention schema changes: docker compose --profile setup up db-setup.
3. Restart the runtime containers: docker compose up -d api worker.
4. Confirm /v1/health/ready returns HTTP 200 before routing client traffic to the new version.

User-facing modules

• Object types & schema registry – define domain-specific attributes, geometry allowances, and validation rules. Publishes draft → sandbox → published versions plus public ID templates.
• Objects & spatial layers – store tenant-scoped records (GeoJSON, attributes, workflow state) with time-travel history, vector tiles, GeoJSON streams, and OGC API Features output.
• Workflows & rules – author finite-state machines, explain allowed transitions, and bind JsonLogic/spatial rules to guard actions.
• Automation engine – evaluate triggers (object events, schedules, webhooks), run match/condition/effect pipelines, and emit audit plus metrics per run.
• Relations graph – model directional relations between objects, including metadata and CRUD APIs.
• Query service – expose DTO-based filters and an advanced JSON DSL (POST /v1/queries/objects/run) for analytics use cases.
• Access control & licensing – centrally manage permission policies, JWT claims, tenant quotas, and license installation.
• Audit & health – tamper-evident audit log with proof endpoints and liveness/readiness health checks for orchestration.

System Architecture

API entry points

The OpenAPI document (/openapi/v1.json) and GraphQL schema (/graphql/schema.gql) describe every contract. Key REST endpoints for day-to-day use:

Platform management

• GET /v1/health/live|ready – readiness for load balancers.
• GET /v1/auth/me – inspect the currently active identity and capabilities.
• GET/POST /v1/license – read or install a signed license.
• GET/PUT /v1/permissions/policy – tenant-level RBAC policy (fields, objects, relations, workflows, automation effects).
• GET /v1/audit/events/:id/proof – verify a record in the audit hash chain.

Domain modeling and data access

• GET/POST/PATCH/DELETE /v1/object-types – create and maintain type definitions, workflow assignments, and auto-generated public IDs.
• POST /v1/objects / PATCH /v1/objects/:id – mutate objects with optimistic locking; GET /v1/objects?asOf= enables historical reads.
• GET /v1/objects/:id/history – inspect both valid time and transaction time history.
• POST /v1/objects/:id/workflow/transitions – move an object across workflow states; pair with GET /v1/objects/:id/workflow/explain-transitions to explain guards.
• GET /v1/layers/objects, /v1/layers/objects/stream, /v1/layers/tiles/:layer/:z/:x/:y – spatial exports, NDJSON streams, and vector tiles.
• GET /v1/relations / POST /v1/relations – list or create relations; CRUD endpoints exist for updates and deletes as well.
• GET /v1/queries/objects / POST /v1/queries/objects/run – quick DTO filters or the JSON DSL for complex filtering/sorting.
• GET /v1/schema-registry/{entityType}/{entityId} – manage schema versions for object types, workflows, or rules.

Automation and monitoring

• GET/POST /v1/rules plus POST /v1/rules/:id/publish – lifecycle management for reusable rule definitions.
• GET/POST /v1/automation/rules – CRUD for automation rules, versions, publish flows, and webhook trigger tokens.
• GET /v1/automation/rules/:id/runs – inspect recent executions; GET /v1/automation/rules/:ruleId/runs/:runId drills into metrics and failures.
• POST /v1/automation/triggers/:slug – authenticated webhook entry point for external events.
• POST /v1/outbox/flush – manually flush queued domain events (useful for on-prem support and debugging).

Client SDKs and dependencies

The platform ships generated clients for TypeScript/Node.js, Python, and .NET so you can build admin tools, integrate with CI/CD workflows, and automate platform operations.

TypeScript / Node.js

import { TerragnosAdminClient } from '@terragnos/sdk-admin';

const client = new TerragnosAdminClient({
  baseUrl: 'https://core.example.com/v1/',
  token: process.env.TERRAGNOS_TOKEN,
});

const { items } = await client.listObjects({ typeId: 'supply-route', limit: 25 });
console.log(items.map(item => ({ id: item.objectId, version: item.version })));

Requirements:

• Node.js 18+ (native fetch support).
• Install from your package registry mirror: npm install @terragnos/sdk-admin (the package exposes CommonJS modules under dist/).
• Optional fetchFn override if you need custom HTTP stacks, retry logic, or proxy support.

Python

from terragnos_admin_client import TerragnosAdminClient

client = TerragnosAdminClient("https://core.example.com/v1", token="Bearer ...")
objects = client.request("/objects", method="GET", query={"limit": 50})
print(objects["items"][0])

Requirements:

• Python 3.9+.
• requests is bundled with the generated client; add requests>=2.31 to your environment if you run it outside the provided wheel.
• All known operations are listed in AVAILABLE_OPERATIONS, so you can dynamically enumerate or wrap endpoints even before a helper method exists.

.NET (C#)

using Terragnos.AdminSdk;
using System.Net.Http;

await using var client = new TerragnosAdminClient("https://core.example.com/v1", token: Environment.GetEnvironmentVariable("TERRAGNOS_TOKEN"));
var result = await client.ListRelationsAsync(new Dictionary<string, string?> { ["relationType"] = "supplies" });
Console.WriteLine(result?.ToString());

Requirements:

• Targets .NET 8.
• Relies on System.Net.Http.HttpClient; inject your own instance to centralize timeouts, retry handlers, or proxy credentials.
• TerragnosAdminClient.AvailableOperations enumerates every REST contract for telemetry or higher-level abstractions.

Roadmap & release focus

Planned improvements based on the public backlog:

1. Reliability-first eventing – finalize the outbox/idempotency guards so webhook, automation, and external integrations remain consistent even during restarts.
2. Temporal clarity everywhere – extend asOf time-travel semantics and bitemporal documentation across all read APIs, SDK helpers, and UI annotations.
3. SDK & OpenAPI hygiene – keep the OpenAPI snapshot, GraphQL schema, and the three client SDKs in lockstep with release tags; surface automation explain/test helpers directly inside each SDK.
4. Workflow and rule ergonomics – expose “Explain” endpoints plus guard-rail hints in the console and SDKs, making it easier to understand why a transition or rule evaluation failed.
5. Quota transparency – wire usage tracking counters to the licensing endpoints so operators can see how close each tenant is to its limits before an enforcement event happens.

Release notes under docs/releases/ describe the concrete changes, schema migrations, and manual actions per version. When installing a new tag, always read the matching release document alongside this overview.