Architecture

The supported entry points are src/model.js (ArcGIS model export) and src/server.js (diagnostic HTTP server).

flowchart LR
  A[ArcGIS CDF runtime] --> M[Provider model]
  H[Authenticated diagnostic client] --> S[HTTP server]
  S --> M
  M --> Q[Validated query and bounded worker queue]
  Q --> C[Bounded cache]
  C --> D[Native DuckDB adapter]
  D --> F[Configured source]
  M --> T[Metrics and bounded traces]

Configuration is operator-controlled. Requests cannot choose arbitrary locations, SQL, or extensions. Identifiers are validated/quoted; file locations, geometry, and pagination are bound values.

Each worker shares its initialization promise. Failures close that native instance and permit retry. A bounded queue owns each connection exclusively; one worker is the default, with opt-in independent instances sharing the total configured budget. Queue, initialization, execution and total deadlines bound caller waiting. Disconnect signals cancel admitted work; active interruption retains native ownership until work settles. Queued expiry frees its slot without interrupting another operation. Shutdown rejects new work, drains admitted work, clears timers/cache, and closes the engine.

Source IDs determine order and identity. Geometry is converted to GeoJSON and removed from properties. Full-fetch rejects overflow and checks identifier uniqueness and geometry-family consistency over the returned collection. Diagnostic pagination uses an explicit overflow flag.

Cache keys include bound values, source identity and discovered schema. Entries have TTL, byte/entry limits, and copy isolation. Caches/traces/metrics are per-process and reset on restart. TTL remains the compatibility default; stat, immutable version and strong ETag observations detect changes before and after cached/native reads. P1 design describes snapshot and replica limits.

Liveness checks the HTTP process. Readiness executes SELECT 1; it does not certify source data or credentials. Qualify each source separately with the streaming, uncached preflight scanner. It checks global IDs, schema fingerprints, geometry metadata and full-fetch limits on stable snapshots. The capacity CLI produces latency, queue, cache and memory evidence; see operations.

ArcGIS CDF scaffolding owns GeoServices routes, service registration, deployment manifests, and access control. The model does not authenticate forwarded users or implement tenant policies. Use separately configured provider instances for separate trust domains.

CloudFS is an optional native filesystem adapter with reviewed build verification and temporary credential secrets. Its upstream process-global state requires a dedicated worker process per configuration/account set and one active CloudFS model in that process. Native library loading is lazy so qualification can use an isolated test runtime. See CloudFS scope and release gates.

Original advanced modules live in src/experimental/, outside the runtime/distribution. They need verified adapter interfaces, authorization, durable state where appropriate, and real integration tests. See roadmap.