README
¶
Ortus
Ortus is a Go REST service for point queries on GeoPackage and raster sources: it returns the geographic features (or raster values) that contain a given coordinate, across many sources at once, using spatial SQLite (SpatiaLite).
Features
- Point queries — features containing a coordinate, via
ST_Contains - Many sources at once — query across multiple GeoPackages / raster bundles
- Coordinate transformation — automatic projection to a layer's SRID
- Hot-reload — detects added/removed local sources
- Object storage — load from S3, Azure Blob, or HTTP, with periodic sync
- TLS/HTTPS — optional, via Let's Encrypt (CertMagic)
- Observability — Prometheus metrics + OpenTelemetry tracing
- MCP — an in-process Model Context Protocol server for AI agents
- Rate limiting & CORS — configurable
Quick start
make build
./ortus --storage-path=./data
curl "http://localhost:8080/api/v1/query?lon=13.405&lat=52.52"
The Claude Code skills under .claude/skills/ are symlinks into the
third_party/claude-skills git submodule. Clone with --recurse-submodules
(or run git submodule update --init once), otherwise the symlinks dangle —
and, because some skills back tooling, make doc-drift (its script lives at
.claude/skills/doc-drift-check/scripts/) fails and the pre-PR doc-drift guard
hook is skipped:
git clone --recurse-submodules https://github.com/jobrunner/ortus.git
# existing checkout:
git submodule update --init third_party/claude-skills
# bump to the latest skills (uses the branch pinned in .gitmodules: main):
git submodule update --remote third_party/claude-skills \
&& git add third_party/claude-skills && git commit -m "chore(skills): bump claude-skills"
Documentation
Full docs follow the Diátaxis framework and build with
MkDocs Material (make docs, or make docs-serve for live preview):
- Getting started and other tutorials
- How-to guides — Docker, object storage, sync, TLS, rate limiting, load testing
- Reference — configuration, HTTP API, MCP tools, observability
- Explanation — architecture, decisions (ADRs), technical-debt policy
Contributing? See CONTRIBUTING.md.
License
MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ortus
command
Package main provides the entry point for the Ortus GeoPackage service.
|
Package main provides the entry point for the Ortus GeoPackage service. |
|
internal
|
|
|
adapters/geopackage
Package geopackage provides the SpatiaLite-based GeoPackage repository.
|
Package geopackage provides the SpatiaLite-based GeoPackage repository. |
|
adapters/http
Package http provides the HTTP server and handlers.
|
Package http provides the HTTP server and handlers. |
|
adapters/mcp
Package mcp adapts ortus to the Model Context Protocol so AI agents (Claude Desktop, Claude Code, …) can query traces, source metadata, and perform point queries via a typed tool surface.
|
Package mcp adapts ortus to the Model Context Protocol so AI agents (Claude Desktop, Claude Code, …) can query traces, source metadata, and perform point queries via a typed tool surface. |
|
adapters/metrics
Package metrics provides the OpenTelemetry meter provider that exports metrics both via Prometheus scrape (/metrics) and, optionally, via OTLP push to an external collector.
|
Package metrics provides the OpenTelemetry meter provider that exports metrics both via Prometheus scrape (/metrics) and, optionally, via OTLP push to an external collector. |
|
adapters/raster
Package raster implements the output.SpatialSource port for raster bundles: a ZIP containing a manifest (ortus-raster.yaml), one or more Cloud Optimized GeoTIFFs, and an integer-value -> attribute mapping.
|
Package raster implements the output.SpatialSource port for raster bundles: a ZIP containing a manifest (ortus-raster.yaml), one or more Cloud Optimized GeoTIFFs, and an integer-value -> attribute mapping. |
|
adapters/storage
Package storage provides object storage adapters.
|
Package storage provides object storage adapters. |
|
adapters/telemetry
Package telemetry provides the OpenTelemetry adapter for the Tracer port, including a trace-grouped in-memory ring buffer designed for future MCP queries.
|
Package telemetry provides the OpenTelemetry adapter for the Tracer port, including a trace-grouped in-memory ring buffer designed for future MCP queries. |
|
adapters/tls
Package tls provides TLS configuration using CertMagic.
|
Package tls provides TLS configuration using CertMagic. |
|
adapters/watcher
Package watcher provides file system watching for hot-reload.
|
Package watcher provides file system watching for hot-reload. |
|
app
Package app provides application initialization and wiring.
|
Package app provides application initialization and wiring. |
|
application
Package application contains the application services.
|
Package application contains the application services. |
|
application/gazetteer
Package gazetteer provides the reverse-geocoding and bearing ("Peilung") service.
|
Package gazetteer provides the reverse-geocoding and bearing ("Peilung") service. |
|
config
Package config provides configuration management using Viper.
|
Package config provides configuration management using Viper. |
|
domain
Package domain contains the core business entities and value objects.
|
Package domain contains the core business entities and value objects. |
|
ports/input
Package input defines the primary/driving ports of the application.
|
Package input defines the primary/driving ports of the application. |
|
ports/output
Package output defines the secondary/driven ports of the application.
|
Package output defines the secondary/driven ports of the application. |
|
tools
|
|
|
perfgate
command
Command perfgate is the hard performance gate.
|
Command perfgate is the hard performance gate. |
|
tracecheck
command
Command tracecheck is the trace-coverage gate: it fails the build when a code path that should be visible in a trace is not.
|
Command tracecheck is the trace-coverage gate: it fails the build when a code path that should be visible in a trace is not. |
Click to show internal directories.
Click to hide internal directories.