Overview

Developer documentation for GeoVault, the AcuGIS federation's Go HTTP service for cataloging, versioning, inspecting, editing, transforming, importing, and publishing geospatial datasets.

Purpose

GeoVault is the federation dataset vault: upload or import vector and raster data, keep integer file versions on disk, register live PostGIS and remote GeoServer layers, edit attributes, run geoprocessing transforms, and publish to TileServer, QGIS Publish, or GeoServer.

Major Features

• File-backed dataset versions under /data/projects/.../v{N}/, with a PostgreSQL or JSON version catalog
• Upload plus URL, S3, ESRI FeatureServer/MapServer, GeoServer catalog, and PostGIS registration imports
• Vector transforms: filter, dissolve, clip (new versions with lineage)
• Attribute editing for file-backed OGR vectors and registered PostGIS tables
• Publish vectors to TileServer, rasters to QGIS Publish, and files to GeoServer (async jobs)
• Folders, archive/restore, rename, clone, rollback (file versions), and user metadata
• Server-rendered UI with vanilla JavaScript and federation shared shell assets
• Central session authentication and service/dataset ACLs via the sibling shared/auth package

Architecture Summary

GeoVault is one Go process. Gorilla Mux serves HTML, JSON, and downloads under optional BASE_PATH. A metadata PostgreSQL database is optional, but a reachable Central auth database is mandatory. File bytes live on disk; the version catalog uses PostgreSQL when DATABASE_URL is set and JSON otherwise. GDAL/OGR binaries provide GIS inspection and conversion. See Architecture.

flowchart LR
  Client[Browser / CLI / API] --> Proxy[Apache / reverse proxy]
  Proxy --> GV[GeoVault :8085]
  GV --> Disk[(/data/projects)]
  GV --> Meta[(PostgreSQL metadata)]
  GV --> Auth[(Central auth tables)]
  GV --> GDAL[GDAL / OGR]
  GV --> QGIS[QGIS Publish]
  GV --> Tiles[TileServer]
  GV --> PGSvc[PostGIS Service]
  GV --> GS[GeoServer]
  GV --> S3[S3 / HTTP / ESRI]

Technology Stack

Layer	Technology
Service	Go 1.25, net/http, Gorilla Mux
Database	PostgreSQL via database/sql + lib/pq; JSON fallback only for the version catalog
Auth / ACL	Monorepo shared/auth against Central session and permission tables
GIS tooling	GDAL/OGR (ogrinfo, ogr2ogr, gdalinfo, gdal_translate, gdalwarp), modernc.org/sqlite, go-shp
Cloud	AWS SDK Go (S3-compatible imports)
UI	Go html/template, vanilla JS (web/app.js), Materialize, Leaflet (CDN)
CLI	Sibling acugis Python Typer CLI (../cli) under acugis datasets
Deployment evidence	A parent-repository systemd unit and Apache ProxyPass /geovault configuration

Repository Structure

Path	Role
main.go	Process entrypoint, middleware, route registration, listen on :8085
internal/api/	HTTP handlers (datasets, imports, PostGIS, GeoServer, QGIS proxy, ACL)
internal/db/	Metadata DSN, migrations, dataset/folder/GeoServer persistence
internal/store/	Process-global in-memory version slice with whole-catalog PostgreSQL or JSON persistence
internal/editor/	OGR/SQLite/Shapefile/PostGIS attribute editing
internal/authstore/	Central auth/ACL adapter (shared/auth provider); user/group management remains Central-owned
internal/services/geoserver/	GeoServer REST client and credential encryption
internal/postgisregistry/	PostGIS Service registry proxy helpers
internal/meta/	GDAL/OGR metadata extraction
internal/web/	BASE_PATH / X-Forwarded-* helpers
web/	HTML templates, app.js, CSS, partials
data/	Checked-in sample/local version and metadata JSON; not authoritative production state
deploy/geovault.env	Environment sample (optional /etc/geovault.env)
docs/	Developer documentation and internal audits

Key Concepts

Concept	Meaning
Dataset	Named vault object (file versions, PostGIS pointer, or GeoServer remote stub)
Version	Integer snapshot; file datasets use on-disk v{N}/ directories
Folder	Optional PostgreSQL scope for datasets (folder_id)
Service ACL	Central resource service / geovault with view / edit / admin
Dataset ACL	Central resource geovault_dataset / <name> with view / edit / admin
Datasource	datasource_type / mode / url / meta distinguishing upload, S3, PostGIS, GeoServer remote, ESRI
Job	geoserver_jobs row executed by an in-process goroutine (GeoServer publish or ESRI import); not restart-recovered
BASE_PATH	Optional URL prefix; production Apache typically mounts /geovault

Typical Workflows

1. Authenticate through Central and present its acugis_session cookie, then open /geovault/drive or call the API.
2. Upload or import data (/upload, /import-url, /import-s3, /esri, GeoServer catalog, PostGIS register).
3. Browse versions, preview, and download; optionally edit attributes or run filter/dissolve/clip.
4. Publish: vector → TileServer, raster → QGIS Publish, and/or GeoServer publish job.
5. Manage folders, archive/restore, rename/clone, and QGIS runtime project snapshots via the QGIS proxy APIs.

Working client examples are in Examples. CLI mappings are in CLI.

Documentation

Document	Contents
Installation	Requirements, build, local and production install
Configuration	Environment variables and config files
Architecture	Components, request flows, storage, workers
Database	Schemas, tables, pooling, initialization
Authentication	Sessions, ACLs, permissions, security notes
API	Every registered HTTP endpoint
OpenAPI	OpenAPI 3.1 machine-readable contract
Examples	curl, JavaScript, Python, Go, PHP workflows
CLI	acugis datasets command mapping
Development	Tests, debugging, extension guidance
Deployment	systemd, Apache, reverse proxy, scaling, monitoring
Troubleshooting	Common failures and journal commands
Changelog	Keep a Changelog baseline starting at 1.0.0

Internal consistency notes (not part of the developer install set): geovault-capability-audit.md, geovault-folder-ia.md, and related audit files in this directory.

Verified support boundary

Source review found no GeoVault-owned Dockerfile, Compose file, Makefile, Nginx configuration, health route, metrics route, request-ID middleware, or release automation. The parent repository does contain systemd/geovault.service and Apache proxy configuration. Whether separate private deployment automation exists is unknown. The process-global version slice and whole-table/file replacement strategy mean safe multi-process writes are not established; do not infer horizontal-write scalability from PostgreSQL use.

Security notice

Tracked environment samples may contain credential-like values. They are intentionally not reproduced in this documentation. Treat sample secrets as compromised: strip them from derived configuration, rotate corresponding credentials before production, and prefer a protected secret store or root-readable environment file.

Release status

No GeoVault application version constant or verifiable GeoVault release history was found in the reviewed source. The changelog initializes 1.0.0 on 2026-07-15 as a documentation baseline only; historical application versions cannot be verified.