Guides

Data and status model

Migration 0011_subdomain_intelligence.sql introduces the normalized model.

Migration 0011_subdomain_intelligence.sql introduces the normalized model. Its authoritative root is catalogs, related to catalog_types, catalog_environments, repositories, dns_records, worker_routes, deployments, releases, owners, dependencies, integrations, health, verification, security, roadmap, documentation, artifacts, screenshots, activities, audit events, bookmarks, comments, approvals and notification preferences.

Catalog-specific data is stored in extension_data_json with an explicit schema version. src/lib/catalog-type-schemas.ts validates a strict schema for all 35 types. Unknown extension fields are rejected. Docs, Documentation Systems, AI, Ebook, and Article extend the original catalog type set with governed content, documentation infrastructure, intelligence, publishing, and editorial data.

Semantic inventory

catalog_metrics stores named measurements with an explicit key, label, value, unit, source and observation time. A primary metric represents actual tracked entities; secondary metrics retain distinct meanings. MCP therefore records one server and 252 interfaces, while Microservices records 61 deployable services and 667 capabilities. Scheduled catalog API sync updates only the primary metric.

Catalog surface versus inventory

Environment deployment and operational health describe the catalog application. The independent inventory state is RESERVED, SEEDING, ACTIVE, MATURE, FROZEN or DEPRECATED. A healthy production catalog may truthfully have an empty RESERVED/SEEDING inventory. portfolio_category assigns each catalog to one of eight canonical ecosystem domains.

Governance readiness

The API calculates an 18-control gate covering business/product/technical owners, maintaining team, repository, production URL, health endpoint, documentation, architecture, current security review, data classification, dependencies, consumers, SLA/SLO, on-call, release, verification and lifecycle/deprecation. Manual and scheduled verification treat missing controls as NOT_CONFIGURED. The API rejects MATURE inventory status with GOVERNANCE_REQUIRED until the gate is complete.

Synchronization and drift

sync_runs stores source-specific Catalog API, GitHub, Cloudflare, DNS and repository outcomes. drift_findings stores exact expected and observed JSON per field with OPEN, RESOLVED or IGNORED status. Secret values never enter D1.

Independent state machines

  • Lifecycle: IDEA, PLANNED, BUILDING, ALPHA, BETA, PRODUCTION, DEPRECATED, ARCHIVED.
  • Operational: UNKNOWN, HEALTHY, DEGRADED, DOWN, MAINTENANCE.
  • Publication: DRAFT, SUBMITTED, PENDING_REVIEW, APPROVED, PUBLISHED, REJECTED, ARCHIVED.
  • Verification: UNVERIFIED, PENDING, VERIFIED, PARTIALLY_VERIFIED, FAILED, STALE.
  • Deployment: NOT_CONFIGURED, QUEUED, DEPLOYING, DEPLOYED, FAILED, ROLLED_BACK.
  • Inventory: RESERVED, SEEDING, ACTIVE, MATURE, FROZEN, DEPRECATED.

Transition guards live in intelligence-model.ts. Catalog updates use a numeric version for optimistic concurrency; stale writes return VERSION_CONFLICT.

Migration behavior

The migration uses INSERT OR IGNORE ... SELECT and can be applied repeatedly. It preserves legacy ids, slugs, descriptions, hostnames, links and metadata. Production and development environments are derived using the established catalogs.appneurox.com / catalog-dev.appneural.com convention. A legacy production label maps to lifecycle/publication/deployment only. Health, ownership, security and verification are not invented.

Apply locally:

Terminal
npm run db:migrate:local

Apply production remotely after a backup/read-back check:

Terminal
npx wrangler d1 migrations apply subdomain-catalog-db --remote
Last updated 2 November 2026