Guides

APPNEURAL System Registry & Architecture Intelligence

The application is a Next.js 16/OpenNext Cloudflare Worker backed by a normalized D1 registry.

Current state and gaps

The application is a Next.js 16/OpenNext Cloudflare Worker backed by a normalized D1 registry. The original catalog_items projection is retained only for backward-compatible list and submission flows. The authoritative portfolio is catalogs plus its environments, semantic metrics, relationships, governance, sync evidence and drift findings.

The original model conflates lifecycle, deployment and verification. Its public write routes also allow unauthenticated create, update and delete operations. There is no durable verification evidence, audit trail, environment registry, health history, ownership, repository relationship or infrastructure approval record.

Target architecture

  • Presentation: preserve the APPNEURAL editorial grid and existing / and /item/[slug] links; add directory, health, verification, compare, graph, activity, wizard and administration workspaces.
  • API: Next.js route handlers expose typed JSON contracts with Zod validation, consistent errors, pagination and role-based authorization.
  • Domain: lifecycle, operational, publication, verification and deployment states are independent. Transition guards live in the domain layer.
  • Persistence: normalized D1 tables hold catalogs and operational entities. Catalog-specific extensions remain versioned JSON validated by a schema registry.
  • Edge operations: scheduled Workers enqueue checks; queue consumers execute bounded health and verification jobs. KV is used only for non-authoritative cache/rate-limit data and R2 for generated artifacts/evidence exports.
  • Infrastructure safety: DNS and Worker operations start as dry runs. A stored operation, an idempotency key, an authorized platform role and explicit confirmation are required before execution. Secrets are never returned.
  • Subdomain fallback: each catalog owns one proxied wildcard DNS record and wildcard Worker Route, for example *.editor.appneural.com/* → editor-catalog. Any valid single-label hostname without a catalog row renders that catalog's default page. A more-specific route such as x.editor.appneural.com/* → x-worker can override one hostname without creating a separate x DNS record; the shared wildcard DNS continues to cover it and every unassigned label.
  • Trust: a catalog is not verified because an imported legacy flag said so. Verification is calculated from persisted checks and evidence. Missing data is displayed as UNKNOWN, UNVERIFIED or NOT_CONFIGURED.

Portfolio normalization

Migration 0026_normalize_portfolio_intelligence.sql implements the portfolio normalization: semantic inventory metrics; independent catalog-surface and inventory state; meaningful P0-P3 priorities; an enforceable governance gate; documentation and security evidence; declared architecture relationships; formal concept boundaries; RESERVED/SEEDING empty inventories; one shared core plus strict type extensions; and automatic sync with durable drift findings.

The eight domains are Intelligence, Architecture & Runtime, Developer Platform, Experience & Creation, Applications, Business Systems, Operations & Governance, and Knowledge & Portfolio.

Scheduled reconciliation

The hourly cron checks public DNS and HTTPS, refreshes the primary metric from each catalog /api/items, reads GitHub metadata when GITHUB_TOKEN is present, and compares Cloudflare DNS and Worker routes when read credentials are present. It opens or resolves field-level drift and then stores verification evidence. Missing credentials are NOT_CONFIGURED, never success. Sync never mutates GitHub or Cloudflare infrastructure.

Compatibility and migration

Migration 0011_subdomain_intelligence.sql idempotently maps every legacy row, including PWA, without changing its id, slug, hostname, description or links. It creates production and development environments and a repository relationship when legacy metadata contains a repository. Legacy production labels become lifecycle/publication/deployment state only; operational and verification state remain unknown until fresh evidence exists.

Security boundary

Reads are public for published records. Mutations require ADMIN_TOKEN (or a future identity-provider session) and a role with the requested permission. Callers may not self-assert a privileged role without a valid token. Every important mutation writes an audit event. Production should set the token with wrangler secret put ADMIN_TOKEN; .dev.vars.example contains names only.

Last updated 2 November 2026