Eng#1: Backend sync reconciliation, metrics, OpenAPI by shayancoin · Pull Request #3 · shayancoin/paform

shayancoin · 2025-10-15T00:41:25Z

Eng#1 — Backend sync & operability

PR checklist

Webhook: validator (2 MB/413) + DB dedup (event_id/body_sha) + 202 + background + JSON log.
Counters: sync_success_total, sync_failure_total, sync_records_upserted_total{type}; /metrics exposes them.
Pull: accepts type|sync_type, validates page_size, unified envelope, increments counters.
Tests: webhook dedup/log/counters, pull alias/page_size, manifest coverage (skips if no manifest).
OpenAPI regenerated (docs/API_SPEC.md).
No changes to Eng#2/3 surfaces (viewer/assets/CI wiring untouched).

Notes

Admin: after Eng#3 assets PR merges, mark assets workflow as Required on main.

Summary by CodeRabbit

Documentation
- Replaced legacy textual API docs with a complete OpenAPI 3.1 specification.
- Documented comprehensive endpoints (e.g., examples, materials, modules, quote generation, CNC export, sync, root, healthcheck, metrics).
- Added standardized request/response schemas, error formats, and security schemes.
- Improves clarity, consistency, and compatibility with tooling (e.g., client generation, validation).
- No runtime behavior changes.

coderabbitai · 2025-10-15T00:41:47Z

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

📥 Commits

Reviewing files that changed from the base of the PR and between 9848a04 and c18ee4b.

📒 Files selected for processing (1)

docs/API_SPEC.md (1 hunks)

 __________________________________________________________________________________
< Controlling complexity is the essence of computer programming. - Brian Kernighan >
 ----------------------------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/sync-reconcile-metrics-openapi

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting

@codex fix this CI failure
@codex address that feedback

chatgpt-codex-connector · 2025-10-15T00:44:51Z

docs/API_SPEC.md

+    "/api/sync/hygraph": {
+      "post": {
+        "tags": [
+          "sync"
+        ],
+        "summary": "Hygraph Webhook",
+        "description": "Webhook receiver:\n- HMAC validated (dependency)\n- Single size guard (2MB) already enforced by dependency; body/raw set on request.state\n- DB dedup via SyncEvent(event_id, body_sha256 unique)\n- 202 fast-ack with background processing (pull_all)\n- Structured JSON log line and Prometheus counters",
+        "operationId": "hygraph_webhook_api_sync_hygraph_post",
+        "responses": {
+          "202": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {


Hygraph webhook advertises 202 while implementation returns 200

The specification for POST /api/sync/hygraph describes a 202 success response and “fast-ack with background processing”. The actual handler (backend/api/routes_sync.py) simply returns a dict without setting status_code=202, so FastAPI responds with 200. This mismatch will cause clients following the spec to treat the 200 responses as unexpected and breaks monitoring dashboards that rely on a 202 acknowledgement. Either change the code to return 202 or update the spec to document the 200 behaviour.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2025-10-15T00:44:51Z

docs/API_SPEC.md

+    "/api/sync/hygraph/pull": {
+      "post": {
+        "tags": [
+          "sync"
+        ],
+        "summary": "Hygraph Pull",
+        "description": "Admin pull:\n- Auth via Bearer token (constant-time compare)\n- Accepts \"type\" or \"sync_type\" + optional \"page_size\"\n- Validates positive page_size and caps inside service (\u2264200)",
+        "operationId": "hygraph_pull_api_sync_hygraph_pull_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "additionalProperties": true,
+                "type": "object",
+                "title": "Body"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Hygraph Pull Api Sync Hygraph Pull Post"
+                }
+              }
+            }
+          },


OpenAPI lists /api/sync/hygraph/pull although no such route exists

The spec introduces a secured POST /api/sync/hygraph/pull endpoint, but there is no implementation anywhere in the backend (rg "hygraph/pull" backend yields nothing). Publishing a non-existent admin sync endpoint will lead operators to 404s and erodes trust in the spec. Either add the pull route or remove it from the OpenAPI document.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2025-10-15T00:44:51Z

docs/API_SPEC.md

+    "/metrics": {
+      "get": {
+        "summary": "Metrics",
+        "operationId": "metrics_metrics_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }


/metrics path documented without an implemented Prometheus endpoint

The new OpenAPI document exposes a GET /metrics path returning JSON, but the backend codebase contains no route or instrumentation for /metrics (rg "metrics" backend finds nothing). Requests to this path will return 404 and monitoring tooling configured from the spec will fail. Either instrument the app with a metrics endpoint or remove the path from the spec.

Useful? React with 👍 / 👎.

docs(api): regenerate OpenAPI spec

c18ee4b

chatgpt-codex-connector bot reviewed Oct 15, 2025

View reviewed changes

shayancoin merged commit b683750 into main Oct 15, 2025
1 of 6 checks passed

coderabbitai bot mentioned this pull request Oct 21, 2025

Align CNC export endpoint with versioned exports API #521

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Eng#1: Backend sync reconciliation, metrics, OpenAPI#3

Eng#1: Backend sync reconciliation, metrics, OpenAPI#3
shayancoin merged 1 commit intomainfrom
feat/sync-reconcile-metrics-openapi

shayancoin commented Oct 15, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Oct 15, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Oct 15, 2025

Uh oh!

chatgpt-codex-connector bot Oct 15, 2025

Uh oh!

chatgpt-codex-connector bot Oct 15, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

shayancoin commented Oct 15, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Oct 15, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shayancoin commented Oct 15, 2025 •

edited by coderabbitai bot

Loading