Architecture

Runtime view

flowchart LR
    B[Browser or API client] --> P[Apache reverse proxy]
    P --> S[PostGIS Service<br/>Go HTTP process]
    S --> M[(Metadata PostgreSQL)]
    S --> A[(Central auth and ACL PostgreSQL)]
    S --> T[(Managed PostgreSQL servers)]
    S --> F[Backup/import filesystem]
    S --> X[pg_dump / pg_restore<br/>ogr2ogr / ogrinfo]
    S --> J[journalctl / systemctl<br/>psql and maintenance tools]

One process hosts Gorilla Mux routes, HTML templates/static assets, authorization middleware, and an in-process job worker. The worker polls every two seconds and processes at most one claimed job per tick in this process. Multiple service instances can safely compete for jobs through FOR UPDATE SKIP LOCKED, but deployment guidance for multi-instance operation is not present.

Request path

1. Forwarded protocol and host are applied.
2. RequireLogin resolves an acugis_session.
3. RequirePostGISServiceAccess maps method/path to view, edit, or admin on Central resource service/postgis_service.
4. A route reads metadata and/or performs operations against a registered PostgreSQL server.

All registered routes, including /login, pages, assets, API routes, and WebSocket upgrades, pass through both global middleware. Consequently the local /login redirect route itself requires a valid session in normal mode; unauthenticated middleware redirects directly to Central before that handler runs.

Components

Package	Responsibility
internal/db, internal/store	Metadata connection, startup migration, persistence
internal/authstore, sibling shared/auth	Central session lookup, groups, resources, service ACLs
internal/cluster, internal/postgres	PostgreSQL lifecycle and SQL connections
internal/access, internal/grants	Roles, memberships, privilege bundles, HBA management
internal/settings	Curated pg_settings read/update
internal/introspect	Schemas, tables, sizes, row estimates, indexes, geometry/SRID summaries
internal/jobs	Persistent queue and six job executors
internal/backup	pg_dump/pg_restore artifacts
internal/ingest	Uploads and GDAL vector imports
internal/terminal	WebSocket protocol, PTY/restricted shell/log stream, audit logs
internal/web, web/	Base-path handling, templates, browser assets

Background work

Work	Trigger/schedule	Behavior
Stale-job recovery	Once at worker startup	Requeues every running job; the passed 30-minute duration is ignored.
Job polling	Every 2 seconds	Claims oldest queued job and executes one synchronously.
Create database	API queue	Creates DB, optionally enables PostGIS, records size/version.
Delete database	API queue	Terminates sessions, drops DB, deletes registry row.
Clone database	API queue	Same connection only; terminates source sessions and uses CREATE DATABASE ... TEMPLATE.
Backup	API queue	Runs pg_dump -Fc, verifies a non-empty artifact.
Restore	API queue	Runs pg_restore --clean --if-exists --no-owner --no-acl, ensures PostGIS.
Vector import	API queue	Runs ogrinfo/ogr2ogr, ensures schema/PostGIS, updates metadata.
Terminal keepalive	During terminal bridges	A 30-second ticker participates in terminal connection handling.

Cancellation changes only queued jobs. Running subprocesses are not cancelled by POST /api/jobs/{id}/cancel.

Failure and consistency characteristics

• Migrations are inline idempotent SQL, not numbered/versioned migration files.
• Creating a database registry row occurs before creating its job; job-creation failure can leave a provisioning row.
• Clone target rows are also created before job creation.
• A restore-to-new database can succeed before its registry update fails; the job then reports that partial state.
• Applying HBA rules writes a timestamped backup, writes the managed block, then reloads PostgreSQL. A reload error does not automatically restore the original file.
• There are no distributed locks around HBA files, storage artifacts, or settings changes.
• HTTP server timeouts and graceful shutdown are not configured; http.ListenAndServe is used directly.

See Database, Authentication, and API.