Core Concepts

Before building on Terragnos Core, internalize the vocabulary that appears across the API, worker, console, and documentation. These concepts define how data is modeled, secured, and automated inside every enterprise deployment.

Tenants & identity

• Tenant – The top-level isolation boundary. Each object type, object instance, workflow, automation rule, and license usage counter is scoped to a tenant. JWTs carry the tenant claim, and Row Level Security enforces it at the database layer.
• Identity – Represented by sub (user ID) + roles/scope. The API exposes GET /v1/auth/me so you can verify the active identity, capabilities, and tenant context.
• Roles & Permission Policy – A tenant-specific policy controls which roles can mutate fields, objects, relations, workflows, and automation effects. Manage via GET/PUT /v1/permissions/policy or the console. Built-in defaults (owner, admin, operator, etc.) can be extended with custom identifiers.

Data modeling primitives

Concept	Description	Key docs
Object Type	Schema definition that describes attributes, geometry requirements, and workflow bindings. Versioned via the schema registry.	Object Types Guide
Schema Registry	Draft → sandbox → publish lifecycle for object types, workflows, and rules. Ensures compatibility before activation.	Object Types Guide
Object	Tenant-scoped record with attributes, GeoJSON geometry, workflow state, and time-travel history. REST endpoints live under /v1/objects.	Quickstart, API Overview
Relation	Directed link between objects, optionally decorated with metadata. Useful for supply chains, ownership graphs, etc.	Relations Guide
Layer Definition	Reusable spatial export configuration that powers GeoJSON feeds and vector tiles.	Layers Guide

Temporal model

Every object maintains:

• Transaction time – when the change was written to the database (createdAt, updatedAt).
• Valid time – the period during which the data represents reality (valid_from, valid_to).

Read endpoints accept asOf to reconstruct historical state, and the worker uses the same history for audit trails and automation context.

Process automation

• Workflow – A versioned finite-state machine that tracks each object's lifecycle. Transitions can require rules, automation hooks, or manual approval. Key endpoints: /v1/workflows, /v1/objects/:id/workflow/transitions, /v1/objects/:id/workflow/explain-transitions.
• Rules – Reusable logic snippets (JsonLogic, spatial guards) that validate workflow transitions or other actions. Managed via /v1/rules and versioned alongside bindings.
• Automation Rules – Pipeline definitions triggered by internal events, schedules, or webhooks. Each rule evaluates matches, conditions, and effects (internal mutations or HTTP calls). The worker executes them; management endpoints live under /v1/automation/rules.

Workflow Example

Automation Rule Pipeline

Eventing & integrations

• Outbox – Every mutation writes to event_outbox, guaranteeing at-least-once delivery to downstream consumers. The worker flushes the outbox and emits audit events.
• Webhooks – Incoming automation triggers (POST /v1/automation/triggers/:slug) and potential outbound notifications. Authentication relies on secret references resolved at runtime.
• Query Service – DTO-based filters and a JSON DSL for analytics workloads (/v1/queries/objects, /v1/queries/objects/run). Useful for integrating external BI tooling.

Observability & governance

• Audit Log – Tamper-evident chain of events. Use GET /v1/audit/events/:id/proof to verify integrity for compliance audits.
• Health Probes – /v1/health/live and /v1/health/ready inform orchestrators when the API is ready or needs a restart.
• Licensing & Quotas – Each deployment loads a Terragnos-issued license. Quotas (object count, workflow runs, queries, etc.) are enforced per tenant, and overruns return HTTP 403. Installation steps are covered in the Licensing guide.

Platform components

Component	Purpose	Notes
API Service	REST/GraphQL API exposing endpoints for objects, workflows, automation, and platform management.
Worker Service	Background service that processes the outbox, automation pipelines, workflow jobs, and scheduled tasks.
Admin Console	Web-based UI for operators to manage object types, schemas, workflows, permissions, and automation rules.
SDKs	Generated clients (TypeScript, Python, .NET) for programmatic access and integration.
Documentation	Self-hosted documentation site for on-prem deployments.

Putting it together

1. Install the platform and license (Quickstart or Deployment guide).
2. Define object types and workflows using the console or API.
3. Populate objects and relations, ensuring the right tenants and roles are in place.
4. Layer automation rules or external webhooks to orchestrate downstream systems.
5. Observe health, monitor quotas, and rotate licenses as part of regular operations.

Understanding these primitives makes the remaining guides easier to consume. Use the sidebar to navigate to the specific module you want to configure or integrate next.