Overview

Developer documentation for Central, the AcuGIS federation portal service. Central owns / and presents the unified browser entry point for maps, dashboards, reports, datasets, applications, and curated links. It stores portal metadata and platform identity/ACL data; Apache (or another reverse proxy) remains responsible for routing traffic to downstream services.

Purpose

Central is the platform's:

• User-facing portal and discovery catalog
• Session-login authority that issues the shared acugis_session cookie
• Personal-access-token (PAT) issuer for automation
• Administration surface for users, groups, resources, and ACLs
• Curated portal-card catalog with optional import from service discovery feeds

Major Features

• HTML portal shell (/, /catalog, /services, /administration, /account, admin pages)
• JSON APIs for health, identity, catalog aggregation, portal cards, PATs, and admin CRUD
• PostgreSQL-backed users, sessions, PATs, groups, resources, and permissions
• Optional operation without a database (portal/auth disabled; process still serves HTML stubs and health)
• Same-origin discovery aggregation for Dashboards, QGIS Publish, TileServer, Jasper, and GeoVault
• In-memory catalog cache (default 45s TTL)
• Thumbnail upload storage on the local filesystem
• Duplicate admin JSON surface under /admin/api/* for UI compatibility

Architecture Summary

Central is a single Go process using net/http. It binds plain HTTP (default :8888), renders Go HTML templates from web/, and optionally connects to PostgreSQL with pgxpool. Authentication uses the shared sibling module ../shared/auth. Downstream discovery is synchronous HTTP from Central to Apache-proxied same-origin URLs. See Architecture.

flowchart LR
  Client[Browser / CLI / API] --> Proxy[Apache TLS reverse proxy]
  Proxy --> Central[Central :8888]
  Central --> PG[(PostgreSQL)]
  Central --> FS[Thumbnail files]
  Central --> Cache[In-memory catalog cache]
  Central --> Disc[Discovery APIs]
  Disc --> Dashboard
  Disc --> QGIS
  Disc --> Tiles
  Disc --> Jasper
  Disc --> GeoVault

Technology Stack

Layer	Technology
Service	Go 1.22, net/http, Go html/template
Database	PostgreSQL via github.com/jackc/pgx/v5 (pgxpool)
Auth / ACL	Sibling shared/auth (cookie sessions + bearer PATs)
Shared UI	Sibling shared/ui served at /shared/ui/
Browser UI	Vanilla JS, Materialize CSS/JS (CDN), Google Fonts / Material Icons
Build	build.sh / build.ps1 with CGO_ENABLED=0
CLI	Sibling Python acugis CLI (../cli) for login, whoami, catalog, and search
Deployment evidence	systemd unit + parent-repo Apache reverse-proxy configs

Repository Structure

Path	Role
main.go	Entrypoint, route registration, login/logout, portal/catalog handlers
admin_auth.go	Admin user/group/resource/permission HTTP handlers
admin_resource_acl.go	Resource ACL overview and matrix editor handlers
user_tokens.go	Account page and PAT list/create/revoke handlers
internal/portal/	Card/auth persistence, discovery, catalog aggregation, thumbnails, ACLs
internal/web/	BASE_PATH and X-Forwarded-* helpers
web/	HTML templates, CSS, and client JavaScript
deploy/systemd/	systemd unit and /etc/central.env example
deploy/sql/portal_cards.sql	Partial card-table SQL (not a full schema substitute)
build.sh, build.ps1	Release-style binary builds
docs/	This documentation set

Key Concepts

Concept	Meaning
Portal card	Curated entry on the home portal (portal_cards)
Manual card	Card without both source_service and source_resource_id; visibility uses is_public
Resource-backed card	Card linked to a Central resources row; visibility uses group ACLs
Catalog	Aggregated discovery gateway (GET /api/catalog)
Session	Opaque cookie acugis_session; only SHA-256 hash stored server-side
PAT	Personal access token (agp_...) accepted as Authorization: Bearer
Group ACL	view / edit / admin grants on resources for auth_groups
Public group	Implicit group used for public visibility; seeded at schema init
Administrators	Platform admins; protected group; see all portal cards
BASE_PATH	Optional URL prefix applied to all registered routes at startup

Typical Workflows

1. Sign in at /login; Central sets acugis_session.
2. Browse / for ACL-filtered portal cards, or /catalog for aggregated discovery.
3. Open Account to create a PAT for CLI/automation (agp_...).
4. As admin, manage cards under /admin/portal, users/groups under /admin/users and /admin/groups, and ACLs under /admin/permissions.
5. Import discovered resources into portal cards, or grant Public/view so they appear for anonymous discovery.

Working client examples: Examples. CLI mappings: CLI.

Documentation

Document	Contents
Installation	Requirements, build, local and production install
Configuration	Environment variables and secrets
Architecture	Components, request flows, storage, integrations
Database	Tables, indexes, initialization, pooling
Authentication	Sessions, PATs, roles, ACL semantics
API	Every registered HTTP endpoint
OpenAPI	OpenAPI 3.1 machine-readable contract
Examples	curl, JavaScript, Python, Go, PHP workflows
CLI	Mapping to sibling acugis CLI commands
Development	Layout, tests, extension guidance
Deployment	systemd, Apache, TLS, scaling, monitoring
Troubleshooting	Common failures and debug commands
Changelog	Keep a Changelog baseline starting at 1.0.0

Verified support boundary

Source review found no Central-owned Dockerfile, Compose file, Nginx config, Kubernetes manifests, CI workflow, metrics endpoint, background job runner, or first-party CLI binary inside this directory. Production launch evidence is systemd plus parent-repository Apache configs. Discovery service URLs are hard-coded relative paths and are not environment-configurable.

If historical release tags cannot be established for Central alone, this documentation set initializes the public API/changelog baseline at 1.0.0.

Security notice

Tracked environment samples elsewhere in the monorepo may contain credential-like values. They are intentionally not reproduced here. Treat sample secrets as compromised: strip them from derived configuration, rotate corresponding credentials before production use, and prefer a protected secret store or root-readable environment file such as /etc/central.env.