🗺️ Datasynx Cartography

AI-powered Infrastructure Cartography & SOP Generation

Claude IS the agent — it decides which read-only commands to run, analyses the output, and stores results via custom MCP tools into SQLite. No hand-written parsers, diff logic, or decision trees.

📦 npm · 💼 LinkedIn · 🐛 Issues

What it does

$ datasynx-cartography discover

  CARTOGRAPHY  localhost
  ─────────────────────────────────────────────
  🔖  Browser bookmarks scanned…
  🖥  All installed apps scanned…
  +  Node  saas_tool:vscode           [saas_tool]   90%
  +  Node  saas_tool:cursor           [saas_tool]   90%
  +  Node  saas_tool:docker-desktop   [saas_tool]   90%
  +  Node  saas_tool:github.com       [saas_tool]   70%  🔖
  +  Node  web_service:localhost:5432 [database]    90%
  +  Node  web_service:localhost:6379 [cache]       90%
  ~  Edge  web_service:app → web_service:localhost:5432  uses
  ─────────────────────────────────────────────
  DONE  9 nodes, 3 edges  in 38.4s

  WEITERSUCHEN  — Discovery interaktiv verfeinern
  → Suche nach (Enter = Beenden): hubspot windsurf
  ⟳  Suche nach: hubspot windsurf
  +  Node  saas_tool:hubspot.com      [saas_tool]   70%  🔖
  +  Node  saas_tool:windsurf         [saas_tool]   90%

Features

| Feature | Details | |---------|---------| | Installed App Scan | Scans /Applications, Homebrew, dpkg/snap/flatpak, Spotlight + 60 known tools via which | | Browser Bookmarks | Chrome, Firefox, Safari, Brave, Edge — extracts business/SaaS domains automatically | | Cloud Scanning | AWS (EC2/RDS/EKS/S3), GCP (Compute/GKE/Cloud Run), Azure (AKS/WebApps), Kubernetes | | Human-in-the-Loop | Chat with the agent mid-discovery: type "hubspot windsurf" to search for specific tools | | SOP Generation | Automatically generates Standard Operating Procedures from observed workflows | | SOP Dashboard | HTML dashboard with all SOPs, step details, frequency stats | | Export Formats | Mermaid topology, D3.js interactive graph, Backstage YAML, JSON, SOP Markdown | | Safety First | PreToolUse hook blocks all destructive Bash commands — 100% read-only |

Requirements

• Node.js ≥ 18
• Claude CLI — the Agent SDK starts it as a subprocess

npm install -g @anthropic-ai/claude-code
claude login

Install

npm install -g @datasynx/agentic-ai-cartography

Quick Start

# Check all requirements
datasynx-cartography doctor

# Discover your full infrastructure (one-shot, Claude Sonnet)
# → scans bookmarks, installed apps, local services, cloud, config files
# → then interactive follow-up: type tool names to search further
datasynx-cartography discover

# Seed infrastructure manually (JSON file or interactive)
datasynx-cartography seed --file infra.json
datasynx-cartography seed

# View all browser bookmarks
datasynx-cartography bookmarks

# Full feature reference
datasynx-cartography docs

Commands

Cartography (Discovery)

datasynx-cartography discover [options]

  --entry <hosts...>    Start hosts          (default: localhost)
  --depth <n>           Max crawl depth      (default: 8)
  --max-turns <n>       Max agent turns      (default: 50)
  --model <m>           Claude model         (default: claude-sonnet-4-5-...)
  --org <name>          Org name for Backstage YAML
  -o, --output <dir>    Output directory     (default: ./datasynx-output)
  -v, --verbose         Show agent reasoning

Discovery pipeline (automatic, in order):

1. Browser bookmarks — every domain classified as saas_tool or web_service
2. Installed apps — all IDEs, business tools, dev tools, browsers
3. Local services — ss, ps, port-to-service mapping
4. Cloud & Kubernetes — AWS/GCP/Azure/k8s (skipped gracefully if not configured)
5. Config files — .env, docker-compose.yml, etc.
6. Human-in-the-loop — interactive follow-up after initial scan

Analysis & Export

datasynx-cartography export [session-id] [options]
  --format <fmt...>    mermaid, json, yaml, html, sops  (default: all)
  -o, --output <dir>   Output directory
datasynx-cartography show [session-id]             Session details + node list
datasynx-cartography sessions                      List all sessions
datasynx-cartography bookmarks                     View all browser bookmarks
datasynx-cartography seed [--file <path>]          Manually add infrastructure nodes
datasynx-cartography doctor                        Check all requirements + cloud CLIs
datasynx-cartography docs                          Full feature reference

Output Files

datasynx-output/
├── catalog.json               Full machine-readable dump
├── catalog-info.yaml          Backstage service catalog
├── topology.mermaid           Infrastructure topology (graph TB)
├── dependencies.mermaid       Service dependencies (graph LR)
├── topology.html              Interactive D3.js force graph
├── sop-dashboard.html         HTML dashboard with all SOPs + frequency stats
├── sops/
│   ├── deploy-check.md
│   └── db-migration.md
└── workflows/
    └── workflow-001.mermaid

Cost Estimate

| Mode | Model | Interval | per Hour | per 8h Day | |------|-------|----------|----------|------------| | Discover | Sonnet | one-shot | $0.15–0.50 | one-shot | | SOP generation | Sonnet | one-shot | $0.01–0.03 | one-shot |

Architecture

CLI (Commander.js)
  └── Preflight: Claude CLI + API key + interval validation
      └── Agent Orchestrator (src/agent.ts)
          └── runDiscovery()     Claude Sonnet + Bash + MCP Tools
              ├── scan_bookmarks()         browser bookmark extraction
              ├── scan_installed_apps()    /Applications, brew, dpkg, which
              ├── scan_k8s_resources()     kubectl (readonly)
              ├── scan_aws/gcp/azure()     cloud CLI scans (readonly)
              └── ask_user()               human-in-the-loop questions
              └── Custom MCP Tools → CartographyDB (SQLite WAL)

Safety

Every Bash call is guarded by a PreToolUse hook that blocks destructive commands: rm, mv, dd, chmod, kill, docker rm/run/exec, kubectl delete/apply/exec, redirects (>), pipes to shell, and more. Claude only reads — never writes, never deletes.

Public API

import {
  CartographyDB,
  runDiscovery,
  exportAll,
  exportSOPDashboard,
  safetyHook,
  defaultConfig,
} from '@datasynx/agentic-ai-cartography';

// Run a discovery pass with optional user hint
await runDiscovery(config, db, sessionId, onEvent, onAskUser, 'hubspot windsurf');

Built by

License

MIT — © Datasynx AI