# Graph Report - .  (2026-04-08)

## Corpus Check
- 189 files · ~104,440 words
- Verdict: corpus is large enough that graph structure adds value.

## Summary
- 538 nodes · 664 edges · 71 communities detected
- Extraction: 91% EXTRACTED · 9% INFERRED · 0% AMBIGUOUS · INFERRED: 61 edges (avg confidence: 0.68)
- Token cost: 0 input · 0 output

## God Nodes (most connected - your core abstractions)
1. `MCP Server Documentation` - 14 edges
2. `Authentication Documentation` - 11 edges
3. `GearBox REST API Reference` - 8 edges
4. `handleResponse()` - 7 edges
5. `Codebase Improvements Implementation Plan` - 7 edges
6. `GearBox Architecture Overview` - 6 edges
7. `Testing Improvements Implementation Plan` - 5 edges
8. `Catalog-Driven Gear Flow Design Spec` - 5 edges
9. `Codebase Improvements Design Spec` - 5 edges
10. `MCP OAuth 2.1 Server Design Spec` - 5 edges

## Surprising Connections (you probably didn't know these)
- `Logto OIDC Authentication` --semantically_similar_to--> `Authentication Documentation`  [INFERRED] [semantically similar]
  README.md → docs/authentication.md
- `Auth Model (Public Read, Authenticated Write)` --semantically_similar_to--> `Authentication Documentation`  [INFERRED] [semantically similar]
  CLAUDE.md → docs/authentication.md
- `Garage S3-Compatible Storage` --semantically_similar_to--> `imageSourceUrl Schema Column Design`  [INFERRED] [semantically similar]
  README.md → docs/superpowers/specs/2026-04-03-image-url-fetching-design.md
- `MCP Research Thread Workflow` --semantically_similar_to--> `Thread Resolution Pattern`  [INFERRED] [semantically similar]
  docs/mcp-server.md → CLAUDE.md
- `MCP Server Overview (19 Tools)` --semantically_similar_to--> `MCP Server Documentation`  [INFERRED] [semantically similar]
  CLAUDE.md → docs/mcp-server.md

## Hyperedges (group relationships)
- **Dual Auth Mode: API Key + OAuth Bearer for MCP** — auth_api_keys, spec_mcp_oauth_flow, mcp_server_doc, claude_oauth_endpoints [EXTRACTED 0.90]
- **Research Thread Workflow: create→add→compare→resolve** — mcp_research_workflow, api_thread_resolve, claude_thread_resolution, mcp_tools_threads [INFERRED 0.88]
- **Server Hardening: DB Middleware + Params + Error Handler + Rate Limit** — plan_codebase_db_middleware, plan_codebase_params, plan_codebase_error_handler, plan_codebase_rate_limit [EXTRACTED 0.92]

## Communities

### Community 0 - "Candidate Card UI"
Cohesion: 0.05
Nodes (4): handleSave(), validate(), LucideIcon(), toPascalCase()

### Community 1 - "Collection Forms & Pickers"
Cohesion: 0.06
Nodes (8): handleSubmit(), validate(), handleConfirmCreate(), handleKeyDown(), handleSelect(), handleStartCreate(), handleSubmit(), validate()

### Community 2 - "Thread Modal Workflows"
Cohesion: 0.06
Nodes (11): handleAddToExistingThread(), handleCreateThreadAndAdd(), handleSubmit(), apiDelete(), ApiError, apiGet(), apiPatch(), apiPost() (+3 more)

### Community 3 - "Auth Documentation"
Cohesion: 0.07
Nodes (33): API Key Auth (X-API-Key header), Argon2 Password Hashing (Bun.password), Cookie Session Auth (gearbox_session), Authentication Documentation, First-Time Setup Flow, Auth Frontend Behavior (read-only for anon), Auth Middleware Behavior (5-step rule), MCP Implementation Structure (src/server/mcp/) (+25 more)

### Community 4 - "Auth Services & Middleware"
Cohesion: 0.08
Nodes (7): deleteCategory(), getOrCreateUncategorized(), createTestDb(), getOrCreateDb(), exchangeCode(), generateTokens(), refreshAccessToken()

### Community 5 - "Architecture Overview (CLAUDE.md)"
Cohesion: 0.08
Nodes (26): GearBox Architecture Overview, Auth Model (Public Read, Authenticated Write), Client Layer (React 19 + TanStack), Database Schema (Drizzle ORM), MCP Server Overview (19 Tools), MCP OAuth 2.1 Endpoints, Server Layer (Hono + Drizzle), Shared Layer (Zod Schemas + Types) (+18 more)

### Community 6 - "Formatters & Icon Picker"
Cohesion: 0.1
Nodes (2): useOnboardingComplete(), useSetting()

### Community 7 - "Dialogs & FAB Menu"
Cohesion: 0.1
Nodes (0): 

### Community 8 - "MCP Category & Item Tools"
Cohesion: 0.1
Nodes (0): 

### Community 9 - "REST API Endpoints"
Cohesion: 0.1
Nodes (20): Candidate Reorder Endpoint (PATCH /api/threads/:id/candidates/reorder), Categories API Endpoints, GearBox REST API Reference, Images API Endpoints, Items API Endpoints, Settings API Endpoints, Setup Items Atomic Replace (PUT /api/setups/:id/items), Setups API Endpoints (+12 more)

### Community 10 - "Image Service & MCP Tools"
Cohesion: 0.16
Nodes (2): getImageUrl(), withImageUrl()

### Community 11 - "Codebase Improvement Plans"
Cohesion: 0.23
Nodes (12): Codebase Improvements Implementation Plan, Explicit DB Context Middleware Plan, Client Error Boundary Plan (TanStack Router), Centralized Error Handler Plan, Route Parameter Validation Plan (parseId), Rate Limiting on Auth Endpoints Plan, Split Collection Route into Tab Components Plan, Explicit DB Context Middleware Design (+4 more)

### Community 12 - "Thread Service Layer"
Cohesion: 0.18
Nodes (0): 

### Community 13 - "Thread Creation UI"
Cohesion: 0.2
Nodes (2): handleClose(), resetForm()

### Community 14 - "Testing & Component Plans"
Cohesion: 0.18
Nodes (11): Reusable UI Components Policy, Testing Improvements Implementation Plan, E2E Database Seed Plan (e2e/seed.ts), parseId Unit Tests Plan, Playwright E2E Test Setup Plan, Rate Limiter Unit Tests Plan, Code Quality Round 2 Design Spec, Test Helper Drizzle Migration Design (replace hand-written SQL) (+3 more)

### Community 15 - "Setup Service Layer"
Cohesion: 0.22
Nodes (0): 

### Community 16 - "Rate Limiting"
Cohesion: 0.32
Nodes (3): cleanup(), getClientIp(), rateLimit()

### Community 17 - "Item Service Layer"
Cohesion: 0.29
Nodes (0): 

### Community 18 - "CSV Import/Export"
Cohesion: 0.38
Nodes (3): importItemsCsv(), parseCsv(), parseCsvLine()

### Community 19 - "DB Schema & Seeding"
Cohesion: 0.33
Nodes (0): 

### Community 20 - "SQLite→Postgres Migration"
Cohesion: 0.47
Nodes (3): main(), migrateTable(), resetSequences()

### Community 21 - "Global Item Service Tests"
Cohesion: 0.4
Nodes (0): 

### Community 22 - "v1.4 Feature Specs"
Cohesion: 0.4
Nodes (5): v1.4 Collection Tools Design Spec, CSV Import/Export Feature Design, Item Duplication Feature Design, Item Quantity Feature Design, Setup Impact Preview Feature Design

### Community 23 - "Public Profile Service"
Cohesion: 0.5
Nodes (0): 

### Community 24 - "OAuth Flow"
Cohesion: 0.67
Nodes (2): escapeHtml(), renderConsentForm()

### Community 25 - "Global Items Route Tests"
Cohesion: 0.5
Nodes (0): 

### Community 26 - "Thread Route Tests"
Cohesion: 0.5
Nodes (0): 

### Community 27 - "Setup Route Tests"
Cohesion: 0.5
Nodes (0): 

### Community 28 - "Global Item Search"
Cohesion: 0.67
Nodes (0): 

### Community 29 - "Totals Aggregation"
Cohesion: 0.67
Nodes (0): 

### Community 30 - "Global Item Seeding"
Cohesion: 1.0
Nodes (2): seedGlobalItems(), seedTags()

### Community 31 - "Profile Route Tests"
Cohesion: 0.67
Nodes (0): 

### Community 32 - "OAuth Route Tests"
Cohesion: 0.67
Nodes (0): 

### Community 33 - "Tag Service"
Cohesion: 1.0
Nodes (0): 

### Community 34 - "Collection Summary"
Cohesion: 1.0
Nodes (0): 

### Community 35 - "Dev Seed Display Names"
Cohesion: 1.0
Nodes (0): 

### Community 36 - "Dev Seed Runner"
Cohesion: 1.0
Nodes (0): 

### Community 37 - "Thread Tab Navigation"
Cohesion: 1.0
Nodes (0): 

### Community 38 - "Item Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 39 - "Image Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 40 - "Thread Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 41 - "Storage Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 42 - "OAuth Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 43 - "MCP Tools Tests"
Cohesion: 1.0
Nodes (0): 

### Community 44 - "Item Route Tests"
Cohesion: 1.0
Nodes (0): 

### Community 45 - "Tag Route Tests"
Cohesion: 1.0
Nodes (0): 

### Community 46 - "Category Route Tests"
Cohesion: 1.0
Nodes (0): 

### Community 47 - "Vite Config"
Cohesion: 1.0
Nodes (0): 

### Community 48 - "Drizzle Config"
Cohesion: 1.0
Nodes (0): 

### Community 49 - "Playwright Config"
Cohesion: 1.0
Nodes (0): 

### Community 50 - "Drizzle PG Config"
Cohesion: 1.0
Nodes (0): 

### Community 51 - "Totals Route"
Cohesion: 1.0
Nodes (0): 

### Community 52 - "Tags Route"
Cohesion: 1.0
Nodes (0): 

### Community 53 - "Global Items Route"
Cohesion: 1.0
Nodes (0): 

### Community 54 - "Profiles Route"
Cohesion: 1.0
Nodes (0): 

### Community 55 - "Zod Schemas"
Cohesion: 1.0
Nodes (0): 

### Community 56 - "Migration Runner"
Cohesion: 1.0
Nodes (0): 

### Community 57 - "Category Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 58 - "Auth Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 59 - "CSV Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 60 - "Tag Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 61 - "Setup Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 62 - "Totals Route Tests"
Cohesion: 1.0
Nodes (0): 

### Community 63 - "Profile Service Tests"
Cohesion: 1.0
Nodes (0): 

### Community 64 - "Images Route Tests"
Cohesion: 1.0
Nodes (0): 

### Community 65 - "Error Handling E2E"
Cohesion: 1.0
Nodes (0): 

### Community 66 - "Dashboard E2E"
Cohesion: 1.0
Nodes (0): 

### Community 67 - "Auth E2E"
Cohesion: 1.0
Nodes (0): 

### Community 68 - "Collection E2E"
Cohesion: 1.0
Nodes (0): 

### Community 69 - "Threads E2E"
Cohesion: 1.0
Nodes (0): 

### Community 70 - "Release Process"
Cohesion: 1.0
Nodes (1): Release Process (Gitea Actions)

## Knowledge Gaps
- **50 isolated node(s):** `GearBox Tech Stack`, `Client Layer (React 19 + TanStack)`, `Server Layer (Hono + Drizzle)`, `Shared Layer (Zod Schemas + Types)`, `Setup Item Sync Pattern (Atomic Replace)` (+45 more)
  These have ≤1 connection - possible missing edges or undocumented components.
- **Thin community `Tag Service`** (2 nodes): `tag.service.ts`, `getAllTags()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Collection Summary`** (2 nodes): `collection.ts`, `getCollectionSummary()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Dev Seed Display Names`** (2 nodes): `dev-seed-data.ts`, `categoryDisplayName()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Dev Seed Runner`** (2 nodes): `dev-seed.ts`, `seedDevData()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Thread Tab Navigation`** (2 nodes): `ThreadTabs.tsx`, `CollectionTabs()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Item Service Tests`** (2 nodes): `item.service.test.ts`, `insertGlobalItem()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Image Service Tests`** (2 nodes): `image.service.test.ts`, `fetch()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Thread Service Tests`** (2 nodes): `thread.service.test.ts`, `insertGlobalItem()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Storage Service Tests`** (2 nodes): `storage.service.test.ts`, `constructor()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `OAuth Service Tests`** (2 nodes): `oauth.service.test.ts`, `generatePkce()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `MCP Tools Tests`** (2 nodes): `tools.test.ts`, `parseResult()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Item Route Tests`** (2 nodes): `items.test.ts`, `createTestApp()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Tag Route Tests`** (2 nodes): `tags.test.ts`, `createTestApp()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Category Route Tests`** (2 nodes): `categories.test.ts`, `createTestApp()`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Vite Config`** (1 nodes): `vite.config.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Drizzle Config`** (1 nodes): `drizzle.config.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Playwright Config`** (1 nodes): `playwright.config.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Drizzle PG Config`** (1 nodes): `drizzle-pg.config.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Totals Route`** (1 nodes): `totals.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Tags Route`** (1 nodes): `tags.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Global Items Route`** (1 nodes): `global-items.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Profiles Route`** (1 nodes): `profiles.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Zod Schemas`** (1 nodes): `schemas.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Migration Runner`** (1 nodes): `migrate.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Category Service Tests`** (1 nodes): `category.service.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Auth Service Tests`** (1 nodes): `auth.service.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `CSV Service Tests`** (1 nodes): `csv.service.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Tag Service Tests`** (1 nodes): `tag.service.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Setup Service Tests`** (1 nodes): `setup.service.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Totals Route Tests`** (1 nodes): `totals.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Profile Service Tests`** (1 nodes): `profile.service.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Images Route Tests`** (1 nodes): `images.test.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Error Handling E2E`** (1 nodes): `error-handling.spec.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Dashboard E2E`** (1 nodes): `dashboard.spec.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Auth E2E`** (1 nodes): `auth.spec.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Collection E2E`** (1 nodes): `collection.spec.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Threads E2E`** (1 nodes): `threads.spec.ts`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.
- **Thin community `Release Process`** (1 nodes): `Release Process (Gitea Actions)`
  Too small to be a meaningful cluster - may be noise or needs more connections extracted.

## Suggested Questions
_Questions this graph is uniquely positioned to answer:_

- **Why does `Authentication Documentation` connect `Auth Documentation` to `REST API Endpoints`, `Architecture Overview (CLAUDE.md)`?**
  _High betweenness centrality (0.013) - this node is a cross-community bridge._
- **Why does `MCP Server Documentation` connect `Auth Documentation` to `Architecture Overview (CLAUDE.md)`?**
  _High betweenness centrality (0.010) - this node is a cross-community bridge._
- **Why does `GearBox REST API Reference` connect `REST API Endpoints` to `Auth Documentation`?**
  _High betweenness centrality (0.007) - this node is a cross-community bridge._
- **Are the 3 inferred relationships involving `MCP Server Documentation` (e.g. with `MCP Server Overview (19 Tools)` and `MCP Server Design Spec`) actually correct?**
  _`MCP Server Documentation` has 3 INFERRED edges - model-reasoned connections that need verification._
- **Are the 3 inferred relationships involving `Authentication Documentation` (e.g. with `Auth Model (Public Read, Authenticated Write)` and `Authentication Design Spec`) actually correct?**
  _`Authentication Documentation` has 3 INFERRED edges - model-reasoned connections that need verification._
- **Are the 6 inferred relationships involving `handleResponse()` (e.g. with `apiGet()` and `apiPost()`) actually correct?**
  _`handleResponse()` has 6 INFERRED edges - model-reasoned connections that need verification._
- **What connects `GearBox Tech Stack`, `Client Layer (React 19 + TanStack)`, `Server Layer (Hono + Drizzle)` to the rest of the system?**
  _50 weakly-connected nodes found - possible documentation gaps or missing edges._