Design model

Platform spec article

Design model

Back to Beskid Nexus ◎ Open feature 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

• Feature
  Beskid Nexus

  Parent feature hub

UX shell

Nexus must align with tracker and site chrome:

Element	Contract
Layout	Top navbar (not sidebar)
Kicker	Beskid / Nexus / {repo}
Repo switch	<Select> bound to public catalog
Search	Symbol search over active graph
Theme	Light/dark toggle
Hub	BeskidHub launcher from @beskid/beskid-ui

Interactive UI must use @beskid/ui-react primitives via the #/components/ui alias. Styles must import @beskid/ui-react/styles/shadcn-entry.css and @beskid/beskid-ui/styles/hub.css.

Graph-first landing

Rule	Behavior
N-01	/ must load the first enabled, indexed catalog entry by ascending sortOrder
N-02	When no indexed entry exists, show empty state with sign-in CTA for repo owners
N-03	Deep link ?repo=<catalog-id> must select that entry and load its graph
N-04	Default view must be the graph explorer — not a catalog home grid

Admin flows (add repo, re-index, delete) must appear as dialog or sheet overlays, not separate full-page phases.

Global registry model

The server maintains catalog.json — the authoritative list of public Nexus entries.

Field	Role
id	Stable catalog identifier; used in ?repo= and admin routes
displayName, description, gitUrl, defaultBranch	Public metadata
sortOrder	Landing and selector ordering
indexed, registryName	Whether a LadybugDB export exists and its storage key
lastIndexedCommit, indexedAt, stats	Index freshness and graph size
docStatus	Coarse doc pipeline state (idle | running | failed | ready) — no AI vendor details

Index pipeline: clone → analyze worker → .gitnexus/ index → optional code-doc maintenance worker.

Code documentation vs platform spec

Two distinct layers. Implementations must never merge or paraphrase platform spec into code documentation.

Layer	Source	Stored in	Public exposure
Code documentation	Graph + source snippets	code-docs/{registryName}.json	properties.codeDoc on graph nodes/clusters
Platform spec	site/website/.../platform-spec/	Site only — not copied	Never inlined
Spec links	Read-only spec index search	Same JSON sidecar	properties.specLinks — { title, href }[]

CodeDocRecord

interface CodeDocRecord {
  entityId: string;
  entityKind: 'node' | 'cluster';
  /** Repo-scoped explanation. Must NOT contain platform-spec prose. */
  codeDoc: string;
  /** 0–3 canonical platform-spec URLs. href must exist in spec index. */
  specLinks: Array<{ title: string; href: string }>;
  contentHash: string;
  updatedAt: string;
}

Doc worker rules:

1. Code doc text is generated solely from graph context and file snippets.
2. Spec search is used only by resolve_spec_links to propose canonical URLs — models must not invent paths.
3. When a spec page fully covers a topic, codeDoc stays brief and points via specLinks.
4. Anti-copy validation rejects records where codeDoc contains long n-grams matching spec index chunks.

Public graph API must merge codeDoc and specLinks as separate node properties. UI must render them in distinct sections.

Server architecture

┌─────────────────────────────────────────────────────────────┐
│  gitnexus serve (single process)                            │
├─────────────────────────────────────────────────────────────┤
│  /api/catalog          public registry + graph metadata     │
│  /api/graph              cached LadybugDB export (stream)   │
│  /api/admin/catalog/*  repo-owner gated CRUD + analyze        │
│  /api/mcp                StreamableHTTP (Bearer token)      │
│  /api/internal/code-docs/*  server-only job status (no UI)  │
├─────────────────────────────────────────────────────────────┤
│  catalog.json → clone → analyze → .gitnexus/ index            │
│  post-analyze → doc-maintenance (OpenRouter, hidden)          │
│  code-docs/{registryName}.json                              │
│  spec-index.json (read-only link resolution)                │
└─────────────────────────────────────────────────────────────┘

MCP connect surface

Rule	Contract
N-MCP-01	MCP endpoint must be same-origin {origin}/api/mcp
N-MCP-02	Transport must require Authorization: Bearer $NEXUS_MCP_AUTH_TOKEN
N-MCP-03	Header button Connect MCP must be visible when user is signed in
N-MCP-04	Dialog must show endpoint URL, auth header template, copy actions, and link to MCP contracts

Token value is a deployment secret — UI shows placeholder guidance for operators, not the live secret.

Ownership verification

On mutating catalog operations the server must call GitHub GET /repos/{owner}/{repo} with the user’s hub token and require permissions.admin or owner login match. Env-based admin rosters must not gate per-repo CRUD (operator setup endpoints excepted).