docs(adr-002): align Preflight entity design with Ekrem alignment decisions by GeezerPelletier · Pull Request #2459 · adobe/spacecat-api-service

GeezerPelletier · 2026-05-21T15:47:31Z

Summary

Updates ADR-002 to reflect decisions from the SITES-44675 alignment session with @ekdogan. The ADR was previously marked as pending that alignment — this PR closes it out.

Four changes to the Data Model section:

asyncJobId field added to the entity schema — makes the 1-to-1 FK relationship to AsyncJob explicit; field is never exposed to API consumers
Creation flow documented — controller creates AsyncJob first, receives asyncJobId, then creates Preflight with that FK; ordering ensures the execution primitive exists before the domain record that references it
url index annotation removed — (indexed) on url was inconsistent with the collection method already specifying in-memory filtering; composite (site_id, url) index is explicitly deferred (7-day TTL bounds per-site volume to a manageable size)
Alignment placeholder replaced — "should be aligned with @ekdogan" sentence replaced with a summary of confirmed decisions

…resultType - Flatten GET list response from URL-grouped to flat array sorted by createdAt desc - Add optional ?url= query parameter to filter list by specific page URL server-side - Remove 50-record cap; 7-day AsyncJob TTL is the natural bound, pagination deferred - Rename createdBy.id -> createdBy.email throughout (consistent with profile field name) - Note that createdBy is stored in async job metadata at creation time - Remove resultType and resultLocation from GET by ID response; preflight results are always stored inline in async_jobs.result, never in S3 - Clarify result field: always inline, null until job completes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

@ekremney

…ght entity Rewrites the Data Model section of ADR-002 to introduce a first-class Preflight entity in spacecat-shared-data-access rather than extending the generic AsyncJob model. AsyncJob is shared by preflight, preflight-beta, site-detection, and pr-review — using it as the preflight store forces type discrimination via metadata blobs with no schema enforcement. References SITES-44650 for the spacecat-shared-data-access alignment work with @ekremney. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…yncJob A dedicated Preflight table scopes every row to preflight by definition. Querying AsyncJob by siteId would require a compound (site_id, job_type) filter or composite index to isolate preflight records from the other workflows sharing the table. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The /preflight/beta/jobs endpoint was a temporary internal development path, never intended as a durable design. Calling it out as an anti-pattern is noise — it was always going away. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The /preflight/beta/jobs endpoints were an internal development path with no external consumers. This redesign is their replacement — they are removed outright, not deprecated. Only /preflight/jobs carries a deprecation timeline since it has external consumers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ions - Add asyncJobId FK field (1-to-1 with AsyncJob) to entity schema - Document controller creation flow: AsyncJob first, then Preflight with asyncJobId - Remove (indexed) annotation from url field; composite index deferred - Replace open alignment question with confirmed decisions from SITES-44675 - Clarify TTL: TTL column at 7 days, verify column name in mysticat-data-service Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

codecov · 2026-05-21T15:52:41Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

…oved not deprecated Only /preflight/jobs is the legacy endpoint that continues in parallel. /preflight/beta/jobs is replaced outright by the new endpoints. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-05-21T15:53:59Z

This PR will trigger no release when merged.

Guy Pelletier and others added 30 commits May 8, 2026 14:25

docs: add ADR-002 for preflight API REST redesign

fc0506a

Captures the decision to replace /preflight/jobs and /preflight/beta/jobs with site-scoped endpoints under /sites/:siteId/preflights. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: clarify /preflight/jobs deprecated, /preflight/beta/jobs replaced

58cd0e5

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add description column to proposed endpoints table in ADR-002

156caad

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add explicit request/response schemas to ADR-002

dc39ae4

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: group GET preflights response by URL in ADR-002

2f9a5a0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add data model open question to ADR-002

483ce8a

AsyncJob has no siteId index; GET /sites/:siteId/preflights requires either extending AsyncJob or a new Preflight entity in shared-data-access. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: close data model decision in ADR-002 — extend AsyncJob with sit…

315c06a

…eId index AsyncJob TTL (~7 days) makes a purpose-built Preflight entity unnecessary. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: clarify siteId is optional on AsyncJob for backward compatibility

0564516

Existing job creation paths must not be affected; new endpoints populate siteId at creation time and query by it. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): add createdBy field to preflight API design

e46ad98

Capture IMS caller identity server-side at job creation for audit purposes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): replace pollUrl body field with Location header in POST re…

9137373

…sponse Per RFC 7231 §6.3.3 the created resource URL belongs in the Location response header, not a custom body field. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): clarify preflight/beta/jobs had no external consumers

2fe6c83

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into sites-44290-preflight-api-rest-redesign

1deff77

docs(adr): add updatedAt to GET all preflights list response

a8fb7fc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): remove step field — Mysticat agent always runs full flow

077c3fd

Confirmed by Ben: identify/suggest are no longer separate steps. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): remove mystiqueUrl from public API documentation

fd027b5

Dev-only override, not part of the public contract. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): add errorCode to error response shape for POST preflights

f091baf

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): standardize error codes with PREFLIGHT_ prefix

d5a4298

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into sites-44290-preflight-api-rest-redesign

1180527

docs(adr): expand createdBy to object with id and displayName

dbaff69

Both fields available on IMS profile at no extra cost. Easier to extend in future without breaking API contract. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): add url hostname validation against site's known URLs

06e6600

Prevents callers submitting a url belonging to a different site than the :siteId in the path. Returns PREFLIGHT_INVALID_REQUEST if mismatch. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): split 500 into 502 for Mysticat failures and 500 for local…

0f23de6

… errors Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): cap list endpoint at 50 most recent preflights, defer pagi…

00ac642

…nation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): require siteId ownership check on GET by preflightId

12180f3

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): document resultType and resultLocation in GET by preflight…

6ace542

…Id response Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): note step branching in links.js and metatags.js will be re…

4829a4c

…moved Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): commit to Sunset date process per RFC 8594

188b7d6

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(adr): promote jobType to top-level indexed attribute alongside s…

398ad14

…iteId Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into sites-44290-preflight-api-rest-redesign

6733b5b

GeezerPelletier and others added 10 commits May 13, 2026 08:24

Merge branch 'main' into sites-44290-preflight-api-rest-redesign

60dc1c1

Merge branch 'main' into sites-44290-preflight-api-rest-redesign

bcdf9b4

docs(preflight): fix handle @ekdogan and ticket number in ADR-002

0b5f1f9

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into sites-44290-preflight-api-rest-redesign

d2d69b8

GeezerPelletier temporarily deployed to dev-branches May 21, 2026 16:08 — with GitHub Actions Inactive

GeezerPelletier closed this May 21, 2026

GeezerPelletier deleted the sites-44290-preflight-adr-update branch May 21, 2026 16:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(adr-002): align Preflight entity design with Ekrem alignment decisions#2459

docs(adr-002): align Preflight entity design with Ekrem alignment decisions#2459
GeezerPelletier wants to merge 41 commits into
mainfrom
sites-44290-preflight-adr-update

GeezerPelletier commented May 21, 2026

Uh oh!

codecov Bot commented May 21, 2026

Uh oh!

github-actions Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

GeezerPelletier commented May 21, 2026

Summary

Related

Uh oh!

codecov Bot commented May 21, 2026

Codecov Report

Uh oh!

github-actions Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant