archgraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sangsoo Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# backend-graphing
+
+Backend/frontend code graphing workspace for endpoint-oriented architecture visualization.
+
+## Packages
+- `@backend-graphing/core`: static analyzer, graph model, view builder, exporters
+- `@backend-graphing/cli`: `bgx` command for analyze/export/view/describe/install
+- `@backend-graphing/viewer`: local interactive viewer server + DAG client with code drilldown and task queue
+
+## Quick Start
+```bash
+# install globally from local repo
+npm install -g /Users/sangsoolee/GitHub/backend-graphing
+
+# analyze a backend repo
+node packages/cli/src/index.js analyze \
+  --project /Users/sangsoolee/GitHub/scout-manager-backend \
+  --out scout-manager-backend.graph.json
+
+# export to cypher
+node packages/cli/src/index.js export \
+  --graph scout-manager-backend.graph.json \
+  --format cypher \
+  --out scout-manager-backend.cypher
+
+# generate a filtered view file
+node packages/cli/src/index.js view \
+  --graph scout-manager-backend.graph.json \
+  --spec docs/examples/view-spec.yaml \
+  --out scout-manager-backend.view.json
+
+# launch local viewer
+node packages/cli/src/index.js view \
+  --graph scout-manager-backend.graph.json \
+  --serve \
+  --port 4310
+
+# generate structured bilingual descriptions
+node packages/cli/src/index.js describe \
+  --graph scout-manager-backend.graph.json \
+  --out scout-manager-backend.descriptions.json \
+  --executor codex \
+  --language bilingual \
+  --detail structured
+```
+
+After global install, use:
+```bash
+bgx --help
+bgx analyze --project /absolute/path/to/project --out graph.json
+```
+
+## Install as Codex Skill / Claude Plugin
+
+Global install:
+```bash
+npm install -g /Users/sangsoolee/GitHub/backend-graphing
+```
+
+Automatic import into local assistant folders:
+```bash
+# install both
+bgx install --target all
+
+# codex only
+bgx install --target codex
+
+# claude only
+bgx install --target claude
+```
+
+Custom home paths:
+```bash
+bgx install --target all --codex-home /path/to/.codex --claude-home /path/to/.claude
+```
+
+Dry-run preview:
+```bash
+bgx install --target all --dry-run
+```
+
+## Canonical Graph Format
+`GraphBundle { schemaVersion, createdAt, project, strings[], nodes[], edges[], groups[], indexes }`
+
+Node kinds:
+- `endpoint`, `route_handler`, `function`, `method`, `class`, `object`, `agent`, `langgraph_node`, `mcp_tool`, `module`, `file`, `ui_route`, `ui_component`, `group`, `condition`
+
+Edge kinds:
+- `declares_endpoint`, `handles`, `calls`, `imports`, `invokes_agent`, `uses_mcp_tool`, `langgraph_edge`, `belongs_to_group`, `ui_calls_api`, `frontend_proxies_to_backend`, `evaluates_condition`, `condition_true`, `condition_false`, `condition_case`
+
+## Current Extraction Coverage
+- Express route extraction from `app/router.METHOD` with mounted prefix propagation.
+- Handler linkage from endpoint to route handlers and function symbols.
+- Transitive call graph extraction using TypeScript AST (with local TypeScript module fallback).
+- Conditional flow extraction for `if`/`switch`/ternary branches into explicit condition nodes.
+- LangGraph extraction from `.addNode/.addEdge/.addConditionalEdges` chains.
+- MCP extraction from `*_TOOLS` arrays and `callTool("...")` usage.
+- Grouping by endpoint + secondary overlays by agent/purpose.
+
+## Viewer Capabilities (V2)
+- Endpoint-first directed graph rendering (logical DAG) with conditional edge styling.
+- Grouping by `endpoint`, `agent`, or `purpose` with item selector and search.
+- Node click opens code snippet and related 1-hop context.
+- Sidepanel comment/task queue with status lifecycle and approval-gated execution.
+- Optional descriptions panel source from `bgx describe` artifact.
+
+Executor config template:
+- `docs/examples/executors.example.json` -> copy to `<target-repo>/.bgx/executors.json`
+
+## Tests
+```bash
+npm test
+```
+
+Test suites include:
+- extractor unit tests
+- view and export tests
+- integration checks against `/Users/sangsoolee/GitHub/scout-manager-backend`
+- CLI integration tests
+- viewer asset contract tests
+
+## PRD
+- `.omx/plans/prd-backend-graphing-engine.md`

package/bin/bgx.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../packages/cli/src/index.js';

package/docs/examples/executors.example.json

@@ -0,0 +1,15 @@
+{
+  "codex": {
+    "cmd": "codex",
+    "args": [
+      "run",
+      "{PROMPT}"
+    ]
+  },
+  "claude": {
+    "cmd": "claude",
+    "args": [
+      "{PROMPT}"
+    ]
+  }
+}

package/docs/examples/view-spec.yaml

@@ -0,0 +1,6 @@
+version: "1"
+depth: 3
+groupBy: endpoint
+includeNodeKinds: [endpoint, route_handler, function, agent, mcp_tool, langgraph_node]
+excludeExternal: false
+labelMode: short

package/docs/release.md

@@ -0,0 +1,15 @@
+# Release Notes (Initial)
+
+## Publish Strategy
+1. Build distributable artifacts:
+   - `npm run build`
+2. Verify tests:
+   - `npm test`
+3. Publish packages in dependency order:
+   - `@backend-graphing/core`
+   - `@backend-graphing/viewer`
+   - `@backend-graphing/cli`
+
+## Versioning
+- Follow semver.
+- Keep `schemaVersion` updates explicit when graph model changes.

package/docs/view-spec.md

@@ -0,0 +1,28 @@
+# View Spec
+
+`bgx view --spec <file>` accepts JSON or simple YAML.
+
+Supported fields:
+- `version`: required (`"1"`)
+- `focus`: optional node ID to start traversal
+- `depth`: traversal depth (integer)
+- `groupBy`: `endpoint | agent | purpose`
+- `includeNodeKinds`: array of node kinds to include
+- `excludeExternal`: boolean
+- `collapsePatterns`: reserved array
+- `labelMode`: `short | full`
+
+Notes:
+- `depth` is still supported for `bgx view` artifact generation.
+- Local viewer UI no longer exposes a depth slider; it renders from the generated view and group/search filters.
+
+Example:
+```yaml
+version: "1"
+focus: "endpoint:004415"
+depth: 3
+groupBy: endpoint
+includeNodeKinds: [endpoint, route_handler, function, agent, mcp_tool]
+excludeExternal: false
+labelMode: short
+```

package/integrations/README.md

@@ -0,0 +1,20 @@
+# Assistant Integrations
+
+This folder contains copyable integration bundles for Codex and Claude.
+
+## Codex
+- Source bundle: `integrations/codex/skills/backend-graphing/`
+- Source bundle: `integrations/codex/skills/backend-graphing-describe/`
+- Destination: `$CODEX_HOME/skills/backend-graphing/` (or `~/.codex/skills/backend-graphing/`)
+
+## Claude
+- Source bundle: `integrations/claude/`
+- Plugin destination: `~/.claude/plugins/marketplaces/backend-graphing/`
+- Skill destination: `~/.claude/skills/backend-graphing/`
+- Skill destination: `~/.claude/skills/backend-graphing-describe/`
+
+## Automatic install
+Use:
+```bash
+bgx install --target all
+```

package/integrations/claude/.claude/skills/backend-graphing/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: backend-graphing
+description: Analyze backend/frontend codebases into endpoint-first graph artifacts with `bgx`, and export to Cypher/Mermaid or interactive view JSON.
+---
+
+# Backend Graphing Skill
+
+## When to use
+- User asks to map code architecture by endpoint, agent flow, or functional purpose.
+- User needs low-level call chains and tool orchestration visibility.
+- User wants graph outputs for Neo4j, Mermaid, or local viewer workflows.
+
+## Required input
+- Absolute project path to analyze.
+- Optional frontend project path for UI-route/API linkage.
+
+## Commands
+1. Analyze project:
+```bash
+bgx analyze --project <ABS_PROJECT_PATH> --out <GRAPH_JSON_PATH>
+```
+
+2. Analyze with frontend linkage:
+```bash
+bgx analyze --project <ABS_BACKEND_PATH> --frontend <ABS_FRONTEND_PATH> --out <GRAPH_JSON_PATH>
+```
+
+3. Export Cypher:
+```bash
+bgx export --graph <GRAPH_JSON_PATH> --format cypher --out <GRAPH_CYPHER_PATH>
+```
+
+4. Export Mermaid:
+```bash
+bgx export --graph <GRAPH_JSON_PATH> --format mermaid --out <GRAPH_MMD_PATH>
+```
+
+5. Build view JSON from spec:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --spec <VIEW_SPEC_YAML_OR_JSON> --out <VIEW_JSON_PATH>
+```
+
+6. Launch local viewer:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --serve --port 4310
+```
+
+## Output expectations
+- Graph JSON includes endpoint/handler/call relationships.
+- LangGraph nodes and edges are captured from static source.
+- MCP tool arrays and `callTool(...)` usage appear as explicit tool nodes and edges.
+- Grouping includes endpoint-first plus agent/purpose overlays.
+
+## Notes
+- Analyzer is static (runtime traces are not ingested in current version).
+- JS/TS projects are supported in V1.

package/integrations/claude/.claude/skills/backend-graphing-describe/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: backend-graphing-describe
+description: Generate bilingual natural-language descriptions for endpoint/purpose graph nodes using `bgx describe`.
+---
+
+# Backend Graphing Describe Skill
+
+## When to use
+- You need readable endpoint, function, or purpose descriptions from graph artifacts.
+- You want Korean + English architectural summaries for docs or reviews.
+
+## Required input
+- Graph JSON path (`bgx analyze` output).
+- Output path for description bundle.
+- Executor choice (`codex` or `claude`).
+
+## Commands
+1. Generate description bundle:
+```bash
+bgx describe \
+  --graph <GRAPH_JSON_PATH> \
+  --out <DESCRIPTION_JSON_PATH> \
+  --executor codex \
+  --language bilingual \
+  --detail structured
+```
+
+2. Validate executor template config:
+```bash
+bgx describe \
+  --graph <GRAPH_JSON_PATH> \
+  --out <DESCRIPTION_JSON_PATH> \
+  --executor claude \
+  --executor-config .bgx/executors.json
+```
+
+3. Serve viewer with descriptions loaded:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --serve --descriptions <DESCRIPTION_JSON_PATH>
+```
+
+## Output expectations
+- Writes `DescriptionBundle` JSON with `entries[]` for nodes and groups.
+- Each entry contains structured sections for `ko` and `en`:
+  - `purpose`
+  - `inputs_outputs`
+  - `main_flow`
+  - `conditions`
+  - `dependencies`
+  - `risks_notes`

package/integrations/claude/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "backend-graphing-marketplace",
+  "description": "Local marketplace metadata for backend-graphing plugin",
+  "owner": {
+    "name": "Sangsoo Lee"
+  },
+  "plugins": [
+    {
+      "name": "backend-graphing",
+      "description": "Graph analysis plugin for endpoint-first backend/frontend architecture mapping with bgx",
+      "version": "0.1.0",
+      "source": "./",
+      "author": {
+        "name": "Sangsoo Lee"
+      }
+    }
+  ]
+}

package/integrations/claude/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "backend-graphing",
+  "description": "Graph analysis plugin for endpoint-first backend/frontend architecture mapping with bgx",
+  "version": "0.1.0",
+  "author": {
+    "name": "Sangsoo Lee"
+  },
+  "keywords": ["graph", "architecture", "endpoint", "langgraph", "mcp", "code-analysis"]
+}

package/integrations/claude/skills/backend-graphing/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: backend-graphing
+description: Analyze backend/frontend codebases into endpoint-first graph artifacts with `bgx`, and export to Cypher/Mermaid or interactive view JSON.
+---
+
+# Backend Graphing Skill
+
+## When to use
+- User asks to map code architecture by endpoint, agent flow, or functional purpose.
+- User needs low-level call chains and tool orchestration visibility.
+- User wants graph outputs for Neo4j, Mermaid, or local viewer workflows.
+
+## Required input
+- Absolute project path to analyze.
+- Optional frontend project path for UI-route/API linkage.
+
+## Commands
+1. Analyze project:
+```bash
+bgx analyze --project <ABS_PROJECT_PATH> --out <GRAPH_JSON_PATH>
+```
+
+2. Analyze with frontend linkage:
+```bash
+bgx analyze --project <ABS_BACKEND_PATH> --frontend <ABS_FRONTEND_PATH> --out <GRAPH_JSON_PATH>
+```
+
+3. Export Cypher:
+```bash
+bgx export --graph <GRAPH_JSON_PATH> --format cypher --out <GRAPH_CYPHER_PATH>
+```
+
+4. Export Mermaid:
+```bash
+bgx export --graph <GRAPH_JSON_PATH> --format mermaid --out <GRAPH_MMD_PATH>
+```
+
+5. Build view JSON from spec:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --spec <VIEW_SPEC_YAML_OR_JSON> --out <VIEW_JSON_PATH>
+```
+
+6. Launch local viewer:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --serve --port 4310
+```
+
+## Output expectations
+- Graph JSON includes endpoint/handler/call relationships.
+- LangGraph nodes and edges are captured from static source.
+- MCP tool arrays and `callTool(...)` usage appear as explicit tool nodes and edges.
+- Grouping includes endpoint-first plus agent/purpose overlays.
+
+## Notes
+- Analyzer is static (runtime traces are not ingested in current version).
+- JS/TS projects are supported in V1.

package/integrations/claude/skills/backend-graphing-describe/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: backend-graphing-describe
+description: Generate bilingual natural-language descriptions for endpoint/purpose graph nodes using `bgx describe`.
+---
+
+# Backend Graphing Describe Skill
+
+## When to use
+- You need readable endpoint, function, or purpose descriptions from graph artifacts.
+- You want Korean + English architectural summaries for docs or reviews.
+
+## Required input
+- Graph JSON path (`bgx analyze` output).
+- Output path for description bundle.
+- Executor choice (`codex` or `claude`).
+
+## Commands
+1. Generate description bundle:
+```bash
+bgx describe \
+  --graph <GRAPH_JSON_PATH> \
+  --out <DESCRIPTION_JSON_PATH> \
+  --executor codex \
+  --language bilingual \
+  --detail structured
+```
+
+2. Validate executor template config:
+```bash
+bgx describe \
+  --graph <GRAPH_JSON_PATH> \
+  --out <DESCRIPTION_JSON_PATH> \
+  --executor claude \
+  --executor-config .bgx/executors.json
+```
+
+3. Serve viewer with descriptions loaded:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --serve --descriptions <DESCRIPTION_JSON_PATH>
+```
+
+## Output expectations
+- Writes `DescriptionBundle` JSON with `entries[]` for nodes and groups.
+- Each entry contains structured sections for `ko` and `en`:
+  - `purpose`
+  - `inputs_outputs`
+  - `main_flow`
+  - `conditions`
+  - `dependencies`
+  - `risks_notes`

package/integrations/codex/skills/backend-graphing/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: backend-graphing
+description: Analyze backend/frontend codebases into endpoint-first graph artifacts with `bgx`, and export to Cypher/Mermaid or interactive view JSON.
+---
+
+# Backend Graphing Skill
+
+## When to use
+- User asks to map code architecture by endpoint, agent flow, or functional purpose.
+- User needs low-level call chains and tool orchestration visibility.
+- User wants graph outputs for Neo4j, Mermaid, or local viewer workflows.
+
+## Required input
+- Absolute project path to analyze.
+- Optional frontend project path for UI-route/API linkage.
+
+## Commands
+1. Analyze project:
+```bash
+bgx analyze --project <ABS_PROJECT_PATH> --out <GRAPH_JSON_PATH>
+```
+
+2. Analyze with frontend linkage:
+```bash
+bgx analyze --project <ABS_BACKEND_PATH> --frontend <ABS_FRONTEND_PATH> --out <GRAPH_JSON_PATH>
+```
+
+3. Export Cypher:
+```bash
+bgx export --graph <GRAPH_JSON_PATH> --format cypher --out <GRAPH_CYPHER_PATH>
+```
+
+4. Export Mermaid:
+```bash
+bgx export --graph <GRAPH_JSON_PATH> --format mermaid --out <GRAPH_MMD_PATH>
+```
+
+5. Build view JSON from spec:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --spec <VIEW_SPEC_YAML_OR_JSON> --out <VIEW_JSON_PATH>
+```
+
+6. Launch local viewer:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --serve --port 4310
+```
+
+## Output expectations
+- Graph JSON includes endpoint/handler/call relationships.
+- LangGraph nodes and edges are captured from static source.
+- MCP tool arrays and `callTool(...)` usage appear as explicit tool nodes and edges.
+- Grouping includes endpoint-first plus agent/purpose overlays.
+
+## Notes
+- Analyzer is static (runtime traces are not ingested in current version).
+- JS/TS projects are supported in V1.

package/integrations/codex/skills/backend-graphing-describe/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: backend-graphing-describe
+description: Generate bilingual natural-language descriptions for endpoint/purpose graph nodes using `bgx describe`.
+---
+
+# Backend Graphing Describe Skill
+
+## When to use
+- You need readable endpoint, function, or purpose descriptions from graph artifacts.
+- You want Korean + English architectural summaries for docs or reviews.
+
+## Required input
+- Graph JSON path (`bgx analyze` output).
+- Output path for description bundle.
+- Executor choice (`codex` or `claude`).
+
+## Commands
+1. Generate description bundle:
+```bash
+bgx describe \
+  --graph <GRAPH_JSON_PATH> \
+  --out <DESCRIPTION_JSON_PATH> \
+  --executor codex \
+  --language bilingual \
+  --detail structured
+```
+
+2. Validate executor template config:
+```bash
+bgx describe \
+  --graph <GRAPH_JSON_PATH> \
+  --out <DESCRIPTION_JSON_PATH> \
+  --executor claude \
+  --executor-config .bgx/executors.json
+```
+
+3. Serve viewer with descriptions loaded:
+```bash
+bgx view --graph <GRAPH_JSON_PATH> --serve --descriptions <DESCRIPTION_JSON_PATH>
+```
+
+## Output expectations
+- Writes `DescriptionBundle` JSON with `entries[]` for nodes and groups.
+- Each entry contains structured sections for `ko` and `en`:
+  - `purpose`
+  - `inputs_outputs`
+  - `main_flow`
+  - `conditions`
+  - `dependencies`
+  - `risks_notes`

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "archgraph",
+  "version": "0.1.0",
+  "description": "Endpoint-first static code graph analyzer and interactive viewer for backend/frontend architectures",
+  "type": "module",
+  "bin": {
+    "bgx": "./bin/bgx.js"
+  },
+  "files": [
+    "bin",
+    "integrations",
+    "packages/cli/src",
+    "packages/core/src",
+    "packages/viewer/src",
+    "packages/viewer/public",
+    "README.md",
+    "docs/examples",
+    "docs/view-spec.md",
+    "docs/release.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build-all.mjs",
+    "test": "node --test $(find packages -path '*/test/*.test.js' -print)",
+    "test:core": "node --test $(find packages/core/test -name '*.test.js' -print)"
+  },
+  "keywords": [
+    "backend",
+    "graph",
+    "architecture",
+    "code-analysis",
+    "static-analysis",
+    "api",
+    "endpoint",
+    "visualization",
+    "cli",
+    "langgraph",
+    "mcp"
+  ],
+  "author": "constantlee <constantlee@impakers.club>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lee-Sangsu/backend-graphing.git"
+  },
+  "homepage": "https://github.com/Lee-Sangsu/backend-graphing#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}