Beskid Nexus

Platform spec feature

Beskid Nexus

Back to Tooling ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-public-graph-first-ux Graph-first landing replaces catalog home Accepted

   Nexus opens the first indexed repo graph on / instead of a catalog grid or onboarding flows.

   Context

   GitNexus shipped a CatalogHome grid, DropZone local analyze, onboarding phases, and server-connect wizards. Beskid Nexus is a hosted public explorer for pre-indexed repos — visitors arrive to browse graphs, not to analyze local folders or configure LLM providers.

   Decision

   1. / must load the graph explorer, selecting the first enabled catalog entry with indexed: true ordered by sortOrder.
   2. Deep link ?repo=<catalog-id> selects an explicit entry when present.
   3. CatalogHome, DropZone, QueryFAB, Graph RAG chat, and hosted OnboardingGuide are removed from public UI.
   4. Repo switching happens via navbar <Select>, not a separate home phase.
   5. When no indexed repo exists, show empty state + sign-in CTA for repo owners — not a marketing catalog grid.

   Admin actions (add repo, re-index) must be overlays (dialog/sheet), not full-page route phases.

   Consequences

   • gitnexus-web App phases reduce to boot | setup | server-down | explorer.
   • E2E tests target graph canvas visibility and repo selector — not onboarding wizards.
   • Cached LadybugDB exports remain the only graph source for public visitors.

   Status

   Accepted — supersedes GitNexus CatalogHome as the default Nexus entry experience.

   Open full ADR page

2. 0002-repo-owner-admin GitHub repo owner gates catalog admin Accepted

   Per-repo CRUD and analyze triggers require GitHub-verified ownership via hub token — not env admin rosters.

   Context

   GitNexus used a static admin roster for catalog mutations. Beskid Nexus indexes public graphs for many repositories — administration should follow GitHub ownership, not a deployment-time username list that does not scale across contributors and org repos.

   Instance operators still need bootstrap authority for auth hub pairing and secrets — distinct from day-to-day repo administration.

   Decision

   1. POST/PATCH/DELETE /api/admin/catalog* and POST .../analyze and POST .../refresh-docs require the session user to be owner or admin of the entry's gitUrl per GitHub API (GET /repos/{owner}/{repo} with hub user token).
   2. GET /api/auth/me must expose ownedRepoIds — catalog ids the user may administer — for UI gating.
   3. requireAdmin (env roster) is retained only for POST /api/admin/auth/pair and first-run setup endpoints.
   4. Ownership verification may be cached up to 15 minutes per (login, gitUrl).
   5. Non-owners receive 403 on mutating routes.

   Consequences

   • github-ownership.ts centralizes URL parsing and API checks.
   • Frontend admin sheet gates on ownedRepoIds.includes(activeEntry.id).
   • Public catalog and graph routes remain unauthenticated.

   Status

   Accepted — reference implementation in beskid_nexus/gitnexus/src/server/nexus/github-ownership.ts.

   Open full ADR page

3. 0003-code-docs-separate-from-spec Code docs are repo-scoped; spec is link-only Accepted

   AI-generated codeDoc describes repository code only; platform spec body text never inlined — specLinks are validated hrefs from a read-only index.

   Context

   Nexus runs a hidden doc-maintenance worker after analyze. Without a hard boundary, generated node text could duplicate or paraphrase normative platform-spec MDX — creating two sources of truth and stale copies when spec changes.

   Platform spec on site/website leads code per project policy. Nexus is a reader of spec URLs, not a publisher of spec prose.

   Decision

   1. codeDoc is repo-scoped AI documentation — generated from graph metadata and short file snippets only.
   2. Platform spec MDX bodies are never fed into code-doc prompts as source material.
   3. A read-only spec link index (spec-index.json) stores titles, slugs, and headings for link discovery only.
   4. resolve_spec_links tool returns candidate { title, href } from the index; unknown hrefs must be rejected at commit.
   5. specLinks are 0–3 validated pointers — not summaries of spec content.
   6. code-doc-validator anti-copy guard rejects records containing ≥40 consecutive characters matching spec index excerpts.
   7. Graph API and UI must expose codeDoc and specLinks as separate fields/sections.

   When a topic is fully covered by platform spec, codeDoc stays brief and defers via specLinks.

   Consequences

   • Two-phase doc pipeline: Phase A writes codeDoc from graph context; Phase B attaches links via index search.
   • Public API and UI must not mention OpenRouter, prompts, or AI vendors.
   • Spec deploys require Nexus restart or index rebuild to pick up new link targets.

   Status

   Accepted — normative contracts in design model and contracts.

   Open full ADR page

4. 0004-mcp-connect-surface MCP connect dialog with Bearer auth Accepted

   Signed-in users connect MCP clients to same-origin /api/mcp using deployment Bearer token; UI documents endpoint without exposing secrets.

   Context

   Nexus exposes graph query tools over MCP Streamable HTTP for IDE and agent integrations. Operators deploy a shared NEXUS_MCP_AUTH_TOKEN secret. Users need a discoverable, copy-friendly surface — without embedding secrets in client bundles or public pages.

   Decision

   1. MCP must be mounted at /api/mcp on the Nexus deployment origin.
   2. All MCP requests must require Authorization: Bearer $NEXUS_MCP_AUTH_TOKEN.
   3. Header button Connect MCP must appear for signed-in users (any authenticated session).
   4. ConnectMcpDialog shows:
      • Endpoint URL ({window.location.origin}/api/mcp)
      • Auth header template with placeholder token guidance
      • Copy buttons for URL and header format
      • Link to MCP contracts
   5. The live Bearer token must not be returned by public or session API routes — operators supply it via deployment env (Coolify, etc.).

   Consequences

   • gitnexus-web ships connect-mcp-dialog.tsx wired into NexusAppShell.
   • MCP shares the cached graph data plane with public /api/graph — no parallel index.
   • Platform spec documents the contract; Nexus UI links here for operator and integrator reference.

   Status

   Accepted — complements GitNexus MCP engine retention under Beskid Nexus product shell.

   Open full ADR page

Articles

• Contracts and edge cases Nexus REST API contracts, CodeDocRecord rules, spec link validation, auth/me ownedRepoIds, and MCP Bearer requirements. article Standard Reviewed Sat May 30
• Design model Graph-first landing, navbar shell, global registry, code-doc vs platform-spec separation, and MCP connect surface. article Standard Reviewed Sat May 30

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 4 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Domain
  Tooling

  Parent domain

• Feature
  Graph visualization

  Compiler graph presentation (distinct from Nexus repo graphs)

What this feature specifies

Beskid Nexus is the hosted graph explorer at nexus.beskid-lang.org. The server maintains cached knowledge graphs for a global public registry of Beskid repositories. Visitors land on a graph-first experience — not a catalog grid — and read repo-scoped code documentation on nodes and clusters. Platform spec content stays on this site; Nexus stores only validated links into platform-spec pages, never spec body text.

Repo owners (GitHub-verified) administer their entries: add, re-index, refresh docs, delete. AI documentation runs server-side only and is invisible in public API responses and UI copy.

Access model

Actor	Capabilities
Public visitor	View any indexed repo graph; switch repos via navbar selector; read codeDoc and specLinks on entities
Signed-in GitHub user	Same as public; unlock admin actions for repos they own on GitHub
Repo owner (per repo)	Catalog CRUD, trigger analyze and doc refresh, delete from Nexus, view MCP connect URL
Instance operator	First-run auth hub pairing (NEXUS_SETUP_TOKEN), deployment secrets, webhook HMAC

All indexed graphs are public read. Per-repo private graphs are not in scope.

Removed product surfaces

The following GitNexus-derived flows must not ship in Beskid Nexus public UI:

• DropZone, local analyze, CatalogHome grid
• Cypher QueryFAB, LLM settings, Graph RAG chat
• OnboardingGuide (hosted), advanced server connect from the browser

The analyze engine (LadybugDB, tree-sitter, MCP tools) remains; product chrome is replaced by the graph-first shell aligned with tracker and site.

Implementation anchors

• beskid_nexus/gitnexus/ — Express server, catalog, graph API, MCP, code-doc pipeline
• beskid_nexus/gitnexus-web/ — React shell, repo selector, graph explorer layout
• site/website/src/content/docs/platform-spec/ — normative contracts (this section); read-only spec link index at deploy time via NEXUS_SPEC_ROOT

Articles

• Graph-first landing replaces catalog homeNexus opens the first indexed repo graph on / instead of a catalog grid or onboarding flows.
• Contracts and edge casesNexus REST API contracts, CodeDocRecord rules, spec link validation, auth/me ownedRepoIds, and MCP Bearer requirements.
• Design modelGraph-first landing, navbar shell, global registry, code-doc vs platform-spec separation, and MCP connect surface.