refactor(routing): restructure URLs to /{specId}/{language}/{library} (#5289)

Move language from a top-level URL prefix (`/python/...`) to a middle
segment so the spec slug becomes the canonical SEO entity:

  /{specId}                       cross-language hub
  /{specId}/{language}            language overview
  /{specId}/{language}/{library}  implementation detail

Interactive view collapses into the detail page as an in-place toggle
(`?view=interactive`). Legacy `/python/*` and `/python/interactive/*`
paths fall through to NotFoundPage with no redirects.

Backend: `Library.language` column (default "python"), threaded
through `ImplementationResponse`, `LibraryInfo`, `PlotImage`, `TopImpl`,
`RelatedSpecItem`, `PlotOfTheDayResponse`. Sitemap now emits all three
URL tiers; SEO proxy and OG image routes restructured accordingly.

Frontend: `specPath(specId, language?, library?)` builds the dynamic
path; `RESERVED_TOP_LEVEL` blocks slug collisions. `MastheadRule` and
`useAnalytics` parse path segments instead of hard-coding `/python`.
`InteractivePage` removed; iframe logic merged into `SpecDetailView`.

Subdomain: `python.anyplot.ai` server block added with an internal
nginx rewrite for the SEO bot path (canonical points back to
anyplot.ai). Human SPA path still needs hostname-aware route resolution
before flipping DNS.

Workflow: `spec-create.yml` rejects spec IDs that collide with reserved
top-level routes.

https://claude.ai/code/session_01Sd9QoGJfcNU8yEhsQixDCV

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

.github/workflows/spec-create.yml

@@ -286,6 +286,17 @@ jobs:
             exit 1
           fi
 
+          # Reserved spec slugs collide with top-level frontend routes.
+          # Keep this list in sync with `RESERVED_TOP_LEVEL` in app/src/utils/paths.ts.
+          RESERVED_SLUGS=(plots specs libraries palette about legal mcp stats debug api og sitemap.xml robots.txt)
+          for reserved in "${RESERVED_SLUGS[@]}"; do
+            if [[ "$SPEC_ID" == "$reserved" ]]; then
+              echo "::error::Spec ID '$SPEC_ID' collides with reserved top-level route. Choose a different slug."
+              gh issue comment ${{ github.event.issue.number }} --body "**Error:** Generated spec ID \`${SPEC_ID}\` collides with a reserved top-level route. Please rename the issue with a more specific title and re-trigger."
+              exit 1
+            fi
+          done
+
           echo "specification_id=$SPEC_ID" >> $GITHUB_OUTPUT
           echo "branch=specification/$SPEC_ID" >> $GITHUB_OUTPUT
         env:

alembic/versions/e1f3a2c4d5b6_add_language_to_libraries.py

@@ -0,0 +1,28 @@
+"""add_language_to_libraries
+
+Revision ID: e1f3a2c4d5b6
+Revises: b833d85c09ed
+Create Date: 2026-04-20 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "e1f3a2c4d5b6"
+down_revision: Union[str, None] = "b833d85c09ed"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("libraries", sa.Column("language", sa.String(length=50), nullable=False, server_default="python"))
+
+
+def downgrade() -> None:
+    op.drop_column("libraries", "language")

api/analytics.py

@@ -139,6 +139,7 @@ def track_og_image(
     request: Request,
     page: str,
     spec: str | None = None,
+    language: str | None = None,
     library: str | None = None,
     filters: dict[str, str] | None = None,
 ) -> None:
@@ -150,29 +151,34 @@ def track_og_image(
         request: FastAPI request for headers
         page: Page type ('home', 'plots', 'spec_overview', 'spec_detail')
         spec: Spec ID (optional)
+        language: Language slug (optional) — e.g. "python"
         library: Library ID (optional)
         filters: Query params for filtered home page (e.g., {'lib': 'plotly', 'dom': 'statistics'})
     """
     user_agent = request.headers.get("user-agent", "")
     client_ip = request.headers.get("x-forwarded-for", request.client.host if request.client else "")
     platform = detect_platform(user_agent)
 
-    # Build URL based on page type
+    # Build URL based on page type. Spec routes follow /{spec}/{language}/{library}.
     if page == "home":
         url = "https://anyplot.ai/"
     elif page == "plots":
         url = "https://anyplot.ai/plots"
-    elif spec is not None and library:
-        url = f"https://anyplot.ai/python/{spec}/{library}"
+    elif spec is not None and language and library:
+        url = f"https://anyplot.ai/{spec}/{language}/{library}"
+    elif spec is not None and language:
+        url = f"https://anyplot.ai/{spec}/{language}"
     elif spec is not None:
-        url = f"https://anyplot.ai/python/{spec}"
+        url = f"https://anyplot.ai/{spec}"
     else:
         # Fallback: missing spec for a spec-based page
         url = "https://anyplot.ai/"
 
     props: dict[str, str] = {"page": page, "platform": platform}
     if spec:
         props["spec"] = spec
+    if language:
+        props["language"] = language
     if library:
         props["library"] = library
     if filters:

api/mcp/server.py

@@ -273,6 +273,7 @@ async def get_spec_detail(spec_id: str) -> dict[str, Any]:
             impl_response = ImplementationResponse(
                 library_id=impl.library.id,
                 library_name=impl.library.name,
+                language=impl.library.language,
                 preview_url=impl.preview_url,
                 preview_html=impl.preview_html,
                 quality_score=impl.quality_score,
@@ -291,7 +292,7 @@ async def get_spec_detail(spec_id: str) -> dict[str, Any]:
             implementations.append(
                 {
                     **impl_response.model_dump(),
-                    "website_url": f"{ANYPLOT_WEBSITE_URL}/python/{spec_id}/{impl.library.id}",
+                    "website_url": f"{ANYPLOT_WEBSITE_URL}/{spec_id}/{impl.library.language}/{impl.library.id}",
                 }
             )
 
@@ -367,6 +368,7 @@ async def get_implementation(spec_id: str, library: str) -> dict[str, Any]:
         response = ImplementationResponse(
             library_id=impl.library.id,
             library_name=impl.library.name,
+            language=impl.library.language,
             preview_url=impl.preview_url,
             preview_html=impl.preview_html,
             quality_score=impl.quality_score,
@@ -383,7 +385,10 @@ async def get_implementation(spec_id: str, library: str) -> dict[str, Any]:
             impl_tags=impl.impl_tags,
         )
 
-        return {**response.model_dump(), "website_url": f"{ANYPLOT_WEBSITE_URL}/python/{spec_id}/{library}"}
+        return {
+            **response.model_dump(),
+            "website_url": f"{ANYPLOT_WEBSITE_URL}/{spec_id}/{impl.library.language}/{library}",
+        }
     finally:
         await session.close()
 

api/routers/insights.py

@@ -68,6 +68,7 @@ class TopImpl(BaseModel):
     spec_id: str
     spec_title: str
     library_id: str
+    language: str
     quality_score: float
     preview_url: str | None = None
 
@@ -105,6 +106,7 @@ class PlotOfTheDayResponse(BaseModel):
     description: str | None = None
     library_id: str
     library_name: str
+    language: str
     quality_score: float
     preview_url: str | None = None
     image_description: str | None = None
@@ -121,6 +123,7 @@ class RelatedSpecItem(BaseModel):
     title: str
     preview_url: str | None = None
     library_id: str | None = None
+    language: str | None = None
     similarity: float
     shared_tags: list[str]
 
@@ -253,6 +256,7 @@ async def _build_dashboard(repo: SpecRepository, impl_repo: ImplRepository) -> D
                             spec_id=spec.id,
                             spec_title=spec.title,
                             library_id=lib_id,
+                            language=impl.library.language if impl.library else "python",
                             quality_score=score,
                             preview_url=impl.preview_url,
                         )
@@ -370,12 +374,21 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
     today = date.today().isoformat()
 
     # Collect candidates: implementations with quality_score >= 90 (lightweight, no code loaded)
-    candidates: list[tuple[str, str, str, str, float, str]] = []
+    candidates: list[tuple[str, str, str, str, str, float, str]] = []
     for spec in all_specs:
         for impl in spec.impls:
             if impl.quality_score is not None and impl.quality_score >= 90 and impl.preview_url:
+                language = impl.library.language if impl.library else "python"
                 candidates.append(
-                    (spec.id, spec.title, spec.description or "", impl.library_id, impl.quality_score, impl.preview_url)
+                    (
+                        spec.id,
+                        spec.title,
+                        spec.description or "",
+                        impl.library_id,
+                        language,
+                        impl.quality_score,
+                        impl.preview_url,
+                    )
                 )
 
     if not candidates:
@@ -384,7 +397,7 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
     # Deterministic selection based on date
     seed = int(hashlib.md5(today.encode()).hexdigest(), 16)  # noqa: S324
     idx = seed % len(candidates)
-    spec_id, spec_title, description, library_id, quality_score, preview_url = candidates[idx]
+    spec_id, spec_title, description, library_id, language, quality_score, preview_url = candidates[idx]
 
     # Load deferred fields (code, image_description) for just this one impl
     full_impl = await impl_repo.get_by_spec_and_library(spec_id, library_id)
@@ -395,6 +408,7 @@ async def _build_potd(spec_repo: SpecRepository, impl_repo: ImplRepository) -> P
         description=description,
         library_id=library_id,
         library_name=LIBRARY_NAMES.get(library_id, library_id),
+        language=language,
         quality_score=quality_score,
         preview_url=preview_url,
         image_description=full_impl.review_image_description if full_impl else None,
@@ -518,6 +532,7 @@ async def _build_related(
                 title=spec.title,
                 preview_url=best_impl.preview_url if best_impl else None,
                 library_id=best_impl.library_id if best_impl else None,
+                language=(best_impl.library.language if best_impl and best_impl.library else None),
                 similarity=round(similarity, 3),
                 shared_tags=shared_tags,
             )

api/routers/libraries.py

@@ -26,6 +26,7 @@ async def _refresh_libraries() -> dict:
                 {
                     "id": lib.id,
                     "name": lib.name,
+                    "language": lib.language,
                     "version": lib.version,
                     "documentation_url": lib.documentation_url,
                     "description": lib.description,
@@ -53,6 +54,7 @@ async def _fetch() -> dict:
                 {
                     "id": lib.id,
                     "name": lib.name,
+                    "language": lib.language,
                     "version": lib.version,
                     "documentation_url": lib.documentation_url,
                     "description": lib.description,

api/routers/og_images.py

@@ -90,19 +90,19 @@ async def _fetch_image(url: str) -> bytes:
     return response.content
 
 
-@router.get("/{spec_id}/{library}.png")
+@router.get("/{spec_id}/{language}/{library}.png")
 async def get_branded_impl_image(
-    spec_id: str, library: str, request: Request, db: AsyncSession | None = Depends(optional_db)
+    spec_id: str, language: str, library: str, request: Request, db: AsyncSession | None = Depends(optional_db)
 ) -> Response:
     """Get a branded OG image for an implementation.
 
     Returns a 1200x630 PNG with anyplot.ai header and the plot image.
     """
     # Track og:image request (fire-and-forget)
-    track_og_image(request, page="spec_detail", spec=spec_id, library=library)
+    track_og_image(request, page="spec_detail", spec=spec_id, language=language, library=library)
 
     # Check cache first
-    key = cache_key("og", spec_id, library)
+    key = cache_key("og", spec_id, language, library)
     cached = get_cache(key)
     if cached:
         return Response(content=cached, media_type="image/png", headers={"Cache-Control": "public, max-age=3600"})
@@ -115,8 +115,10 @@ async def get_branded_impl_image(
     if not spec:
         raise HTTPException(status_code=404, detail="Spec not found")
 
-    # Find the implementation
-    impl = next((i for i in spec.impls if i.library_id == library), None)
+    # Find the implementation matching language + library
+    impl = next(
+        (i for i in spec.impls if i.library_id == library and i.library and i.library.language == language), None
+    )
     if not impl or not impl.preview_url:
         raise HTTPException(status_code=404, detail="Implementation not found")
 

api/routers/plots.py

@@ -340,6 +340,7 @@ def _collect_all_images(all_specs: list) -> list[dict]:
                     {
                         "spec_id": spec_obj.id,
                         "library": impl.library_id,
+                        "language": impl.library.language if impl.library else "python",
                         "quality": impl.quality_score,
                         "url": impl.preview_url,
                         "html": impl.preview_html,