Skip to content

Graphify knowledge graphs for AI-assisted development

ConnectSoft uses Graphify (PyPI package graphifyy) to turn repository source — code, project files, and selected docs — into a persistent, queryable knowledge graph that AI coding assistants (Cursor, Claude Code, Codex, and others) can traverse instead of re-reading raw files on every question.

The first pilot repository is ConnectSoft.Extensions. The same pattern applies to other ConnectSoft.* libraries and service templates.

Why Graphify in ConnectSoft?

Large ConnectSoft workspaces span dozens of NuGet libraries and templates. Asking an assistant to "understand the repo" by grepping and opening files is slow, expensive, and does not scale. Graphify builds a structural map once, stores it under graphify-out/, and answers focused questions with graphify query, graphify path, and graphify explain — typically far fewer tokens than naive file reads.

What Graphify produces

After a successful build, each repo contains:

Output Purpose Commit to git?
graphify-out/graph.json Queryable graph (nodes, edges, communities) Yes — team shares one map
graphify-out/GRAPH_REPORT.md God nodes, communities, suggested questions Yes
graphify-out/graph.html Interactive browser visualization Yes (optional --no-viz to skip)
graphify-out/manifest.json Local mtime metadata No — machine-specific
graphify-out/cost.json Local cost tracking No
graphify-out/cache/ Incremental AST / semantic cache No (optional to commit for speed)

Architecture in ConnectSoft

flowchart LR
  subgraph repo [Repository e.g. ConnectSoft.Extensions]
    CS[C# / csproj / sln]
    MD[README and docs]
    GI[.graphifyignore]
  end
  subgraph graphify [Graphify CLI graphifyy]
    AST[Tree-sitter AST extract]
    SEM[Optional semantic LLM extract]
    BUILD[NetworkX graph + Leiden clusters]
  end
  subgraph out [graphify-out]
    JSON[graph.json]
    RPT[GRAPH_REPORT.md]
    HTML[graph.html]
  end
  subgraph assistants [AI assistants]
    CUR[Cursor rule + skill]
    Q[graphify query / path / explain]
  end
  CS --> AST
  MD --> SEM
  GI --> AST
  AST --> BUILD
  SEM --> BUILD
  BUILD --> JSON
  BUILD --> RPT
  BUILD --> HTML
  JSON --> Q
  CUR --> Q
Hold "Alt" / "Option" to enable pan & zoom

Two extraction modes

Mode Command API key When to use
AST / code-only python -m graphify update . Not required Day-to-day C# changes, .csproj, solution layout, README sections parsed structurally
Full semantic python -m graphify extract . --backend <name> Required (or local Ollama) Rich doc semantics, images, papers, cross-file inferred relationships

PowerShell: graphify . is not the same as graphify update .

On the CLI, python -m graphify . is treated as graphify extract . and requires --backend (or a configured API key environment variable). For ConnectSoft library repos without a semantic backend, use python -m graphify update . for builds and refreshes.

Pilot: ConnectSoft.Extensions

Repository: ConnectSoft.Extensions

ConnectSoft.Extensions is a foundational Layer-1 NuGet library (extension methods, domain exception base types, shared utilities). It is a good pilot because the codebase is small but representative: solution layout, multi-target net8.0 / net9.0 / net10.0, unit tests, and README-driven install docs.

Example graph facts (AST-only build):

  • DomainModelException → inherits Exception (extracted from DomainModelException.cs)
  • Solution folders link ConnectSoft.Extensions.csproj and ConnectSoft.Extensions.UnitTests.csproj
  • DomainModelExceptionUnitTests appears as a high-degree test hub

Query from the repo root:

python -m graphify explain "DomainModelException"
python -m graphify query "DomainModelException and unit tests"

Open graphify-out/graph.html in a browser to explore communities visually.

Prerequisites

Requirement Notes
Python 3.10+ python --version
graphifyy on PATH pip install graphifyy or uv tool install graphifyy
Git working tree Graph reports record commit SHA for freshness checks

Official package name is graphifyy (double y). The CLI command remains graphify.

Per-repository setup (ConnectSoft standard)

Run once from the repository root (not the monorepo workspace root unless that repo is the root).

1. Install Graphify and project-scoped Cursor integration

pip install graphifyy

cd D:\Git\ConnectSoft\ConnectSoft.Extensions   # example path

python -m graphify install --project
python -m graphify cursor install --project

This writes (commit these):

Path Role
.cursor/rules/graphify.mdc Always-on Cursor rule: query graph before grepping
.cursor/skills/graphify/SKILL.md /graphify skill for rebuild workflows
.claude/skills/graphify/SKILL.md Same skill for Claude Code (Windows install)
CLAUDE.md Query-first guidance for Claude Code

2. Configure .gitignore

Append Graphify team defaults (keep graph.json, GRAPH_REPORT.md, graph.html tracked):

### Graphify (https://graphify.net/) ###
graphify-out/manifest.json
graphify-out/cost.json
graphify-out/cache/

3. Configure .graphifyignore

Exclude build artifacts and Graphify meta-files so the graph reflects product source, not integration scaffolding:

graphify-out/
.cursor/skills/graphify/
.claude/skills/graphify/
CLAUDE.md
.claude/

**/bin/
**/obj/
.vs/
TestResults/
**/packages/

Adjust per repo (for example add node_modules/ for front-end templates).

4. Build the initial graph (no API key)

python -m graphify update .

Verify:

Test-Path graphify-out/graph.json   # should be True
python -m graphify query "solution structure"

5. Optional: semantic enrichment

When you need deeper doc/image semantics:

# Local Ollama (requires running Ollama + pip install openai)
python -m graphify extract . --backend ollama

# Cloud backends (set env var first)
$env:OPENAI_API_KEY = "..."
python -m graphify extract . --backend openai

Supported backends include gemini, claude, openai, deepseek, kimi, ollama, and bedrock.

6. Optional: auto-rebuild on commit

python -m graphify hook install

Hooks rebuild code AST after commits and register a merge driver for graph.json when multiple branches update the graph.

Daily workflow in Cursor

  1. Pull latest graphify-out/ from git (shared team map).
  2. Ask architecture questions — the .cursor/rules/graphify.mdc rule steers the agent to graphify query when graphify-out/graph.json exists.
  3. After editing .cs files, run:
python -m graphify update .
  1. Commit updated graphify-out/graph.json, GRAPH_REPORT.md, and optionally graph.html with your code change (or in a follow-up commit).

Prefer query over full report

Use graphify query "...", graphify path "A" "B", or graphify explain "Symbol" for focused context. Read GRAPH_REPORT.md only for broad architecture review.

Team git workflow

  1. One developer runs graphify update . (or full extract) and commits graphify-out/ (except ignored cache/manifest/cost).
  2. Everyone else pulls — assistants read the graph immediately.
  3. On stale graphs, compare GRAPH_REPORT.md commit SHA with git rev-parse HEAD.
  4. Re-run graphify update . after code merges.

Rollout status (ConnectSoft libraries)

92 repositories targeted under d:\Git\ConnectSoft (Extensions/SaaS/core, SMS, templates, integration clients, API composition, base template): 89 with graphify-out/graph.json, 3 scaffold repos with integration only (see Scaffold repos).

Batch automation

Use the rollout script (logs to CSV):

cd D:\Git\ConnectSoft\ConnectSoft.Documentation\scripts
.\Invoke-GraphifyRepoSetup.ps1 -Batch All -WorkspaceRoot D:\Git\ConnectSoft
.\Invoke-GraphifyRepoSetup.ps1 -Batch 3          # single batch
.\Invoke-GraphifyRepoSetup.ps1 -RepoPath D:\Git\ConnectSoft\ConnectSoft.Extensions.AI -Force

Log file: ConnectSoft.Documentation/scripts/graphify-rollout-log.csv

Folder exception: package ConnectSoft.Extensions.Diagnostics.HealthChecks.Orleans lives in repo folder HealthChecks.Orleans (not ConnectSoft.Extensions.Diagnostics.HealthChecks.Orleans).

Pilot (pre-rollout)

Repository Nodes
ConnectSoft.Extensions 44
ConnectSoft.Extensions.Testing 129
ConnectSoft.Extensions.Options 350
ConnectSoft.Extensions.DomainModel 49
ConnectSoft.Extensions.DataAnnotations 106
ConnectSoft.Extensions.Logging 525
ConnectSoft.Extensions.MessagingModel 54
ConnectSoft.Extensions.Diagnostics.Metrics 242
ConnectSoft.Extensions.DomainModel.Impl 34
ConnectSoft.Extensions.DatabaseModel 30

Batch 1 — Foundations

Repository Nodes
ConnectSoft.Extensions.ApplicationModel 463
ConnectSoft.Extensions.EntityModel 321
ConnectSoft.Extensions.PersistenceModel 317
ConnectSoft.Extensions.PersistenceModel.DependencyInjection 102
ConnectSoft.Extensions.ServiceModel 75
ConnectSoft.Extensions.WebSecurity 334
ConnectSoft.Extensions.Validation.FluentValidation 319
ConnectSoft.Extensions.Transactions 52
ConnectSoft.Extensions.Aspects.Abstractions 27
ConnectSoft.Extensions.Aspects.Logging 27
ConnectSoft.Extensions.Globalization 165
ConnectSoft.Extensions.Localization 287
ConnectSoft.Extensions.DomainModel.RulesEngine — (scaffold)

Batch 2 — Observability and HTTP

Repository Nodes
ConnectSoft.Extensions.Observability 535
ConnectSoft.Extensions.Telemetry 184
ConnectSoft.Extensions.Diagnostics.HealthChecks 540
ConnectSoft.Extensions.Diagnostics.HealthChecks.SignalR 327
HealthChecks.Orleans 511
ConnectSoft.Extensions.AspNetCore 328
ConnectSoft.Extensions.Compression 372
ConnectSoft.Extensions.RateLimiting 341
ConnectSoft.Extensions.RequestTimeout 325
ConnectSoft.Extensions.Logging.Serilog 405
ConnectSoft.Extensions.SchedulerModel.HangFire 355
ConnectSoft.Extensions.Scalar 272
ConnectSoft.Extensions.Swagger 338

Batch 3 — Persistence

Repository Nodes
ConnectSoft.Extensions.PersistenceModel.NHibernate 653
ConnectSoft.Extensions.PersistenceModel.MongoDb 798
ConnectSoft.Extensions.PersistenceModel.Dapper 1148
ConnectSoft.Extensions.PersistenceModel.EntityFramework 27
ConnectSoft.Extensions.DatabaseModel.MySql 76
ConnectSoft.Extensions.DatabaseModel.PostgreSQL 74
ConnectSoft.Extensions.DatabaseModel.SqlServer 41
ConnectSoft.Extensions.PersistenceModel.ElasticSearch — (scaffold)
ConnectSoft.Extensions.PersistenceModel.Redis — (scaffold)

Batch 4 — Messaging and actors

Repository Nodes
ConnectSoft.Extensions.MessagingModel.MassTransit 450
ConnectSoft.Extensions.MessagingModel.NServiceBus 444
ConnectSoft.Extensions.ActorModel.Orleans 333
ConnectSoft.Extensions.ServiceModel.Grpc 318
ConnectSoft.Extensions.ServiceModel.Grpc.Client 32
ConnectSoft.Extensions.ServiceModel.SignalR 364
ConnectSoft.Extensions.ServiceDiscovery 395

Batch 5 — AI and integration

Repository Nodes
ConnectSoft.Extensions.AI 880
ConnectSoft.Extensions.AI.AgentsFramework 856
ConnectSoft.Extensions.AI.BotFramework 268
ConnectSoft.Extensions.ModelContextProtocol 484
ConnectSoft.Extensions.DataIngestion 417
ConnectSoft.Extensions.OCR 2570
ConnectSoft.Extensions.AuditNet 418
ConnectSoft.Extensions.Compliance 550
ConnectSoft.Extensions.ObjectMapping 96
ConnectSoft.Extensions.ObjectMapping.Abstractions 1371
ConnectSoft.Extensions.ObjectMapping.AutoMapper 1146
ConnectSoft.Extensions.ObjectMapping.Mapster 791
ConnectSoft.Extensions.Http.OAuth2 808

Batch 6 — SaaS and core packages

Repository Nodes
ConnectSoft.Extensions.Saas.Abstractions 215
ConnectSoft.Extensions.Saas.Options 210
ConnectSoft.Extensions.Saas.AspNetCore 136
ConnectSoft.Extensions.Saas.AspNetCore.Grpc 84
ConnectSoft.Extensions.Saas.AspNetCore.SignalR 106
ConnectSoft.Extensions.Saas.Messaging.MassTransit 91
ConnectSoft.Extensions.Saas.Messaging.NServiceBus 85
ConnectSoft.Extensions.Saas.NHibernate 99
ConnectSoft.Extensions.Saas.Orleans 77
ConnectSoft.Extensions.Saas.Billing 62
ConnectSoft.Extensions.Saas.Metering 62
ConnectSoft.Extensions.Saas.Testing 67
ConnectSoft.AspNetCore.Http 56
ConnectSoft.Net.Http 300
ConnectSoft.Text.Json 62

Batch 7 — SMS libraries

Provider-agnostic SMS contracts and provider implementations. See Integration building blocks — SMS.

Repository Nodes Notes
ConnectSoft.Sms.Abstractions 608 ISmsSender and related contracts
ConnectSoft.Sms.Providers.Fake 615 Test double
ConnectSoft.Sms.Providers.ACS 661 Repo folder ConnectSoft.Sms.Providers.ACS; package ConnectSoft.Sms.Providers.AzureCommunicationServices
ConnectSoft.Sms.Providers.Israel019 1226 019 Mobile (Israel) gateway
ConnectSoft.Sms.Providers.Twilio 619 Twilio REST

Run: .\Invoke-GraphifyRepoSetup.ps1 -Batch 7

Batch 8 — Library template and integration client

Starter and vendor API libraries outside the Extensions/SMS batches.

Repository Nodes Role
ConnectSoft.LibraryTemplate 472 dotnet new connectsoft-library starter (connectsoft-library)
ConnectSoft.Deputy.ApiClient 3992 Deputy workforce REST API client — see Integration building blocks

Run: .\Invoke-GraphifyRepoSetup.ps1 -Batch 8

Batch 9 — API composition and orchestration

Repository Nodes Role
ConnectSoft.ApiCompositionOrchestration 983 API composition and workflow orchestration for microservices

Run: .\Invoke-GraphifyRepoSetup.ps1 -Batch 9

Batch 10 — Bill and Braze API clients

Repository Nodes Role
ConnectSoft.Bill.ApiClient 4935 BILL.com (AP, spend, webhooks) — repo name uses Bill, not “Bills”
ConnectSoft.Braze.ApiClient 2451 Braze REST (messaging, export, user data)

Run: .\Invoke-GraphifyRepoSetup.ps1 -Batch 10

Batch 11 — CallRail API client and Base Template

Repository Nodes Role
ConnectSoft.CallRail.ApiClient 5324 CallRail call tracking and attribution API
ConnectSoft.BaseTemplate 15492 Layer 2 microservice kernel (connectsoft-base); large template graph

Run: .\Invoke-GraphifyRepoSetup.ps1 -Batch 11

Scaffold repos (no source yet)

These folders have Graphify integration files but no .cs corpus in the clone yet. See graphify-out/GRAPHIFY_PENDING.md in each repo; run graphify update . after source lands.

  • ConnectSoft.Extensions.DomainModel.RulesEngine
  • ConnectSoft.Extensions.PersistenceModel.ElasticSearch
  • ConnectSoft.Extensions.PersistenceModel.Redis

What every aligned repo contains

.graphifyignore, Graphify .gitignore entries, .cursor/rules/graphify.mdc, .cursor/skills/graphify/, Claude Code skill files, and graphify-out/ (commit graph.json, GRAPH_REPORT.md, graph.html; ignore cache/, manifest.json, cost.json).

Next rollout (outside library scope)

  1. Service templates (ConnectSoft.MicroserviceTemplate, extended Layer 3 installers, …) — tune .graphifyignore for base-template/ and generated scaffold noise where graphs are too large or noisy. ConnectSoft.BaseTemplate is aligned (batch 11); refine ignores if needed.
  2. Documentation repos — semantic extract for large Markdown corpora.
  3. ConnectSoft.Documentation (this site) — optional Graphify for cross-repo doc navigation.

Security and privacy

  • Code AST extraction runs locally via Tree-sitter — no network call.
  • Semantic extraction sends document descriptions to the configured backend, not raw secret files. Do not index .env, keys, or secrets/ — add them to .graphifyignore.
  • Graphify validates URLs and output paths; prefer official graphifyy on PyPI only.

Troubleshooting

Symptom Fix
error: no LLM API key found when running graphify . Use graphify update . for code-only, or pass --backend ollama / set an API key for extract
God nodes are /graphify skill text Add .cursor/skills/graphify/ and .claude/skills/graphify/ to .graphifyignore, delete graphify-out/, rebuild with update .
Graph seems stale Run graphify update .; check commit line in GRAPH_REPORT.md
graphify: command not found Use python -m graphify or install via uv tool install graphifyy

See also