---

🎯 Overview

Dependency Graph Analyzer is a powerful TypeScript library and GraphQL API that analyzes dependency graphs to detect cycles, find strongly connected components, and visualize relationships.

It answers the questions:
> - ✅ Are there circular dependencies in my system?
> - ✅ What's the correct build/install order?
> - ✅ Which packages are most critical?
> - ✅ How do my components relate to each other?

$3

- Tarjan's Algorithm — Find strongly connected components in linear time O(V+E)
- Cycle Detection — Identify circular dependencies with severity levels
- Topological Sort — Get valid dependency ordering
- GraphViz Integration — Beautiful SVG visualizations with highlighted cycles
- Universal — Works for software packages, microservices, courses, teams, or any dependency system
- GraphQL API — Query exactly what you need, nothing more

---

✨ Features

| Feature | Description |
|---------|-------------|
| Cycle Detection | Finds all circular dependencies with ERROR/WARNING severity |
| Tarjan's Algorithm | Computes strongly connected components efficiently |
| Topological Sorting | Returns valid dependency order (if no cycles exist) |
| Critical Package Analysis | Ranks packages by number of dependents |
| GraphViz Visualization | Generates DOT format and SVG images |
| GraphQL API | Flexible query interface - request only what you need |
| TypeScript | Full type safety and IntelliSense support |
| Live API | Production-ready endpoint at https://dep-graph-analyzer.shehan.io/graphql |

---

📦 Installation

$3

Simply send GraphQL queries to:
``
https://dep-graph-analyzer.shehan.io/graphql
`

Quick Test:
`bash
curl -X POST https://dep-graph-analyzer.shehan.io/graphql \
-H "Content-Type: application/json" \
-d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"C\\\"]}\") { stats { totalNodes hasCycles } } }"}'
`

$3

`bash
npm install dependency-graph-analyzer
`

Then use it in your code:

`typescript
import { DependencyGraph, GraphAnalyzer, GraphVisualizer } from 'dependency-graph-analyzer';

const graph = new DependencyGraph();
const g = graph.buildsimple({ 'A': ['B'], 'B': ['C'] });

const analyzer = new GraphAnalyzer(g);
const result = analyzer.analyze();

console.log(result.stats); // { totalNodes: 3, totalEdges: 2, hasCycles: false }
`

$3

`bash


Clone the repository

git clone https://github.com/yourusername/dependency-graph-analyzer.git
cd dependency-graph-analyzer

Install dependencies

npm install

Build the project

npm run build

Run locally

npm start

Server will start at http://localhost:8092/graphql

`

---

🚀 Quick Start

$3

Open in Browser:
Visit https://dep-graph-analyzer.shehan.io/graphql

Example Query:
`graphql
query {
analyze(dependenciesJson: "{\"A\": [\"B\", \"C\"], \"B\": [\"D\"], \"C\": [\"D\"], \"D\": [\"A\"]}") {
stats {
totalNodes
totalEdges
hasCycles
}
cycles {
nodes
severity
}
topological {
valid
order
}
critical {
name
dependents
rank
}
}
}
`

Response:
`json
{
"data": {
"analyze": {
"stats": {
"totalNodes": 4,
"totalEdges": 5,
"hasCycles": true
},
"cycles": [
{
"nodes": ["D", "C", "B", "A"],
"severity": "ERROR"
}
],
"topological": {
"valid": false,
"order": []
},
"critical": [
{
"name": "C",
"dependents": 2,
"rank": 1
}
]
}
}
}
`

$3

`typescript
import { DependencyGraph, GraphAnalyzer, GraphVisualizer } from 'dependency-graph-analyzer';

// Define your dependencies
const dependencies = {
'Frontend': ['React', 'API Client'],
'React': ['API Client'],
'API Client': ['API Server'],
'Backend': ['Database', 'API Server'],
'API Server': ['Business Logic'],
'Business Logic': ['Database'],
'Database': []
};

// Build the graph
const graph = new DependencyGraph();
const g = graph.buildsimple(dependencies);

// Analyze it
const analyzer = new GraphAnalyzer(g);
const analysis = analyzer.analyze();

// Check for cycles
if (analysis.stats.hasCycles) {
console.log('❌ Circular dependencies found:', analysis.cycles);
} else {
console.log('✅ No cycles! Install order:', analysis.topological.order);
}

// Find critical packages
console.log('Most critical packages:', analysis.critical.slice(0, 3));

// Generate visualization
const visualizer = new GraphVisualizer(g);
const result = await visualizer.visualize('svg', true, analysis.cycles);
console.log('SVG:', result.svg);
`

---

🌐 API Reference

$3

Production URL: https://dep-graph-analyzer.shehan.io/graphql

Local Development: http://localhost:8092/graphql (after running npm start)

$3

`graphql
type Query {
analyze(dependenciesJson: String!): AnalysisResult!
}

type AnalysisResult {
cycles: [Cycle!]!
components: [StronglyConnectedComponent!]!
topological: TopologicalOrder!
critical: [CriticalPackage!]!
stats: Stats!
visualization: Visualization!
}

type Cycle {
nodes: [String!]!
severity: Severity! # ERROR or WARNING
}

type StronglyConnectedComponent {
nodes: [String!]!
size: Int!
}

type TopologicalOrder {
order: [String!]!
valid: Boolean!
}

type CriticalPackage {
name: String!
dependents: Int!
rank: Int!
}

type Stats {
totalNodes: Int!
totalEdges: Int!
hasCycles: Boolean!
}

type Visualization {
dot: String! # GraphViz DOT format
svg: String # SVG image (can be rendered in browser)
}
`

$3

Get only statistics:
`graphql
query {
analyze(dependenciesJson: "{\"A\": [\"B\"], \"B\": [\"C\"]}") {
stats {
totalNodes
hasCycles
}
}
}
`

Get only cycles:
`graphql
query {
analyze(dependenciesJson: "{\"express\": [\"body-parser\"], \"body-parser\": [\"express\"]}") {
cycles {
nodes
severity
}
}
}
`

Get visualization only:
`graphql
query {
analyze(dependenciesJson: "{\"A\": [\"B\"], \"B\": [\"C\"]}") {
visualization {
svg
}
}
}
`

Get everything:
`graphql
query {
analyze(dependenciesJson: "{\"A\": [\"B\"]}") {
stats { totalNodes totalEdges hasCycles }
cycles { nodes severity }
components { nodes size }
topological { order valid }
critical { name dependents rank }
visualization { svg dot }
}
}
`

---

📚 Use Cases & Examples

$3

Scenario: Analyze npm package circular dependencies

`graphql
query {
analyze(dependenciesJson: "{\"express\": [\"body-parser\"], \"body-parser\": [\"express\"], \"morgan\": [\"express\"], \"cors\": []}") {
cycles {
nodes
severity
}
stats {
hasCycles
}
}
}
`

Expected: Detects cycle between express ↔ body-parser

$3

Scenario: Visualize service dependencies and find tightly coupled components

`graphql
query {
analyze(dependenciesJson: "{\"api-gateway\": [\"auth-service\", \"user-service\"], \"auth-service\": [\"database\", \"cache\"], \"user-service\": [\"database\", \"email-service\"], \"email-service\": [\"queue\"], \"database\": [], \"cache\": [], \"queue\": []}") {
stats {
totalNodes
hasCycles
}
topological {
order
}
critical {
name
dependents
}
}
}
`

Expected: Database is most critical (3 dependents), no cycles, valid order

$3

Scenario: Plan academic path with prerequisite constraints

`graphql
query {
analyze(dependenciesJson: "{\"Advanced AI\": [\"Machine Learning\", \"Linear Algebra\"], \"Machine Learning\": [\"Statistics\", \"Python Programming\"], \"Deep Learning\": [\"Machine Learning\", \"Calculus\"], \"Statistics\": [\"Math 101\"], \"Linear Algebra\": [\"Math 101\"], \"Calculus\": [\"Math 101\"], \"Python Programming\": [], \"Math 101\": []}") {
topological {
order
valid
}
critical {
name
dependents
}
}
}
`

Expected: Math 101 and Machine Learning are most critical, clear learning path

$3

Scenario: Detect circular build dependencies in monorepo

`graphql
query {
analyze(dependenciesJson: "{\"app\": [\"lib-a\", \"lib-b\"], \"lib-a\": [\"lib-c\"], \"lib-b\": [\"lib-c\"], \"lib-c\": [\"lib-a\"]}") {
stats {
hasCycles
}
cycles {
nodes
severity
}
components {
nodes
size
}
}
}
`

Expected: Cycle detected: lib-a → lib-c → lib-a

$3

Scenario: Generate architecture diagram with SVG

`graphql
query {
analyze(dependenciesJson: "{\"Frontend\": [\"React\", \"API Client\"], \"React\": [\"API Client\"], \"API Client\": [\"API Server\"], \"Backend\": [\"Database\", \"API Server\"], \"API Server\": [\"Business Logic\"], \"Business Logic\": [\"Database\"], \"Database\": []}") {
stats {
totalNodes
totalEdges
hasCycles
}
topological {
order
}
visualization {
svg
dot
}
}
}
`

Expected: Clean architecture, no cycles, SVG showing layered design

---

🧪 Testing

$3

1. Visit: https://dep-graph-analyzer.shehan.io/graphql
2. Paste any query from examples above
3. Click "Run"
4. See results instantly!

$3

`bash


Simple test

curl -X POST https://dep-graph-analyzer.shehan.io/graphql \
-H "Content-Type: application/json" \
-d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"C\\\"]}\") { stats { totalNodes hasCycles } } }"}'

With cycles

curl -X POST https://dep-graph-analyzer.shehan.io/graphql \
-H "Content-Type: application/json" \
-d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"A\\\"]}\") { cycles { nodes severity } } }"}'
`

$3

1. Method: POST
2. URL: https://dep-graph-analyzer.shehan.io/graphql
3. Headers:
- Content-Type: application/json
4. Body (raw JSON):
`json
{
"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"], \\\"B\\\": [\\\"C\\\"]}\") { stats { totalNodes hasCycles } topological { order } } }"
}
`

$3

`javascript
const query =
query {
analyze(dependenciesJson: "{\\"A\\": [\\"B\\"], \\"B\\": [\\"C\\"]}") {
stats { totalNodes hasCycles }
topological { order }
}
}
;

fetch('https://dep-graph-analyzer.shehan.io/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query })
})
.then(res => res.json())
.then(data => console.log(data));
`

$3

`python
import requests

query = """
query {
analyze(dependenciesJson: "{\\"A\\": [\\"B\\"], \\"B\\": [\\"C\\"]}") {
stats { totalNodes hasCycles }
topological { order }
}
}
"""

response = requests.post(
'https://dep-graph-analyzer.shehan.io/graphql',
json={'query': query},
headers={'Content-Type': 'application/json'}
)

print(response.json())
`

$3

If you've cloned the repository:

`bash


Run test suite

npm test

Start local server

npm run dev

Test locally

curl -X POST http://localhost:8092/graphql \
-H "Content-Type: application/json" \
-d '{"query": "query { analyze(dependenciesJson: \"{\\\"A\\\": [\\\"B\\\"]}\") { stats { totalNodes } } }"}'
`

---

📖 Real-World Test Scenarios

See examples/REAL_WORLD_TESTS.md for 10+ real-world test cases including:

- ✅ Python Django dependencies
- ✅ Node.js circular dependencies
- ✅ Microservices architecture
- ✅ Course prerequisites
- ✅ Build system cycles
- ✅ Team skill dependencies
- ✅ Monorepo analysis
- ✅ Diamond dependency problem

---

🔧 Local Development

$3

`bash


Clone repository

git clone https://github.com/yourusername/dependency-graph-analyzer.git
cd dependency-graph-analyzer

Install dependencies

npm install

Build TypeScript

npm run build

Start development server

npm run dev
`

$3

`
dependency-graph-analyzer/
├── src/
│ ├── types.ts # TypeScript interfaces
│ ├── graph.ts # Graph building (buildsimple, build)
│ ├── analyzer.ts # Tarjan's, cycles, topsort, getcritical
│ ├── visualizer.ts # GraphViz integration
│ ├── schema.ts # GraphQL schema
│ ├── resolvers.ts # GraphQL resolvers
│ ├── server.ts # Apollo Server
│ └── index.ts # Library exports
├── examples/
│ ├── test.ts # Example usage
│ ├── viewer.html # SVG viewer
│ └── REAL_WORLD_TESTS.md # Test scenarios
├── dist/ # Compiled JavaScript (gitignored)
├── package.json
├── tsconfig.json
├── Procfile # Heroku deployment
└── README.md
`

$3

`bash
npm run build # Compile TypeScript to JavaScript
npm start # Run production server (dist/server.js)
npm run dev # Run development server with ts-node
npm test # Run test suite
`

---

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙋 Support

- Issues: GitHub Issues
- Live API: https://dep-graph-analyzer.shehan.io/graphql
- Author: @yourusername
- Email: shehan87h@gmail.com

---

🌟 Acknowledgments

- Built with graphlib for graph operations
- Visualization powered by GraphViz via @viz-js/viz
- GraphQL API with Apollo Server
- Deployed on Heroku
- Inspired by the need for universal dependency analysis across all domains

---

🚀 Key Features Recap

✅ Tarjan's Algorithm - O(V+E) complexity for finding SCCs
✅ Cycle Detection - ERROR/WARNING severity levels
✅ Topological Sort - Valid build/install ordering
✅ Critical Analysis - Identify most-depended-on packages
✅ GraphViz Visualization - SVG/DOT format with cycle highlighting
✅ GraphQL API - Query exactly what you need
✅ TypeScript - Full type safety
✅ Live & Production-Ready - https://dep-graph-analyzer.shehan.io/graphql

---