Hosted layers architecture

Meratyn hosted layers let a user publish files that exist only on their computer and then reference those layers from a shared project. Consumers do not install the original files and do not configure WMS, WFS, or other service URLs.

The design intentionally keeps GeoNode headless:

Meratyn is the product boundary. It owns layer IDs, authentication, authorization, project references, service descriptors, and the admin UI. GeoNode manages spatial resource metadata and publication workflows. GeoServer serves representations generated from vector and raster datasets. The asset store covers formats that are more useful when served directly.

Why one API

Projects store a hosted-layer reference, never a GeoNode primary key, GeoServer workspace name, internal hostname, or user-supplied endpoint. A layer response contains one or more normalized service descriptors:

{
  "id": "share-layer-uuid",
  "kind": "vector",
  "services": [
    {
      "id": "wms",
      "type": "wms",
      "url": "https://share.example/api/layers/share-layer-uuid/gateway/wms"
    },
    {
      "id": "wfs",
      "type": "wfs",
      "url": "https://share.example/api/layers/share-layer-uuid/gateway/wfs"
    }
  ]
}

The client selects its preferred supported representation. Meratyn constructs and authorizes any provider request. It must not accept an arbitrary provider URL through its proxy.

Local-file publication

1. The user chooses one or more local files in the desktop app or admin interface.
2. The client performs inexpensive validation and groups sidecars such as Shapefile components.
3. Meratyn creates the layer and upload/import record and reserves quota.
4. The source goes to object storage or a bounded local development volume.
5. The ingestion worker detects the format and chooses a publication strategy.
6. GeoNode imports supported vector/raster datasets. Other formats are converted to a canonical representation or remain direct assets.
7. Meratyn records provider identifiers privately and publishes normalized service descriptors.
8. A project stores the Meratyn layer ID. Opening the project resolves a current, authorized service descriptor.

Publication is asynchronous for real deployments. The layer states are draft, uploading, processing, published, failed, and deleting. Retries must be idempotent and deletion must clean both provider and asset state.

Representation strategy

The simplest reliable rule is “GeoNode for datasets, direct delivery for cloud-native assets.”

This gives ordinary GIS users GeoNode’s catalogue, metadata, permissions, and OGC services without forcing naturally cloud-native formats through GeoServer. The provider is an implementation detail; every representation still appears in the same Meratyn Layers workspace.

Collections are Meratyn-owned organization records layered over the normalized catalogue. They contain stable Meratyn layer IDs and never change a layer’s provider metadata, visibility, or project dependency. Public membership is restricted to public layers so anonymous catalogue reads cannot reveal a private resource.

GeoNode feature mapping

Meratyn exposes these admin areas:

• Overview and publication status
• Metadata, including the provider’s dynamic metadata schema
• Attribute presentation: order, visibility, alias, description, formatting, widget, editability, and constraints
• Styles and default style selection
• Permissions for users, organizations, groups, and public access
• Service representations and downloads
• Versions, lineage, activity, usage, and settings
• Owner identity mapping, publication approval, and featured placement
• GeoNode documents, supplementary assets, and ISO metadata import
• Schema-first vector creation, constraints, validation, and native bulk upsert
• Remote WMS, GeoNode, and ArcGIS catalogues through GeoNode harvesting

GeoNode REST v2 is used when it has a stable operation. A narrow companion Django app supplies identity/ownership, document publication, resource-link discovery, attribute-presentation, and style-lifecycle operations that GeoNode 5.1 does not expose as stable APIs. Geographic access rules remain Meratyn policy, and Meratyn performs guarded feature edits through the internal transactional feature service. This keeps the extension small, avoids a provider database migration, and preserves the Meratyn-local copy if a provider write is temporarily unavailable.

Access model

Discovery and authorization are separate:

• public: discoverable and potentially accessible without signing in
• unlisted: accessible by an authorized link/reference but not listed publicly
• private: visible only to explicitly authorized principals

Grants target a user, organization, or group and independently permit View, Download, Edit, and Manage. Public access is represented by an anonymous principal grant, not by bypassing policy checks.

Private project consumers receive a short-lived access session scoped to the project and referenced layers. Permanent personal tokens must support scopes such as layers:read, layers:publish, and layers:manage. Tokens and provider credentials must never appear in project files or service URLs.

Failure and consistency

Meratyn keeps only the projection needed for navigation, policy, project dependencies, status, and reconciliation. GeoNode remains authoritative for its rich resource model. Provider links record the remote resource ID, revision or ETag, last synchronization time, status, and error.

Upload, import, update, and delete operations are jobs. A provider timeout does not discard the source or pretend publication succeeded. Reconciliation repairs recoverable drift and exposes actionable failures in the admin UI. Provider jobs are durable records rather than UI-only polling state. Catalogue synchronization is idempotent, runs periodically, imports provider-created resources, maps provider owners back to Meratyn identities, and marks missing resources for reconciliation instead of silently deleting local records.

The OGC gateway caches the immutable provider dataset descriptor for each active resource and shares in-flight descriptor lookups. Map clients request many adjacent tiles concurrently; resolving the same dataset once prevents that tile burst from multiplying metadata API traffic. The cache is bounded, and failed lookups are removed so a later request can recover.

Deployment boundary

Only Meratyn and its public asset/OGC gateway require internet exposure. GeoNode Django, GeoServer administration, PostGIS, Redis, memcached, and Celery stay on the private container network. The local Compose profile exposes the GeoNode proxy on a loopback diagnostic port; production should route it only through Meratyn or an authenticated reverse-proxy path.

See Deploy hosted layers for the included stack and operational settings.