URL-Graph

URL-Graph is a Neo4j project designed to store and manage relationships between URLs. This graph database allows you to model and query the connections between different web addresses, providing valuable insights into the structure of your web data.

In the world of web data, understanding relationships between URLs is crucial. The URL-Graph project leverages the power of Neo4j to create a graph representation of these relationships, enabling easy navigation and analysis.

• Graph Database: Utilize Neo4j's powerful graph database to model and store URL relationships.
• Cypher Queries: Leverage the expressive Cypher query language to extract valuable insights from the graph.

Before you begin, ensure you have the following prerequisites installed:

• Neo4j Database Download Neo4j
• Python Download Python

1. Clone the repository:

git clone https://github.com/KingAkeem/url-graph.git

2. Install dependencies:

cd url-graph
pip install -r requirements.txt

Update the configuration file with your Neo4j connection details (config.yml):

neo4j:
  uri: bolt://localhost:7687
  username: your-username
  password: your-password

3. Start the Neo4j database, this will be based on the OS that you're using. Check Neo4j instructions for further explanation.

4. Execute the application

python main.py -u https://www.example.com -d 3 # -u/--url to specify URI and -d/--depth to specify depth of graph

Will dockerize project at some point.

Browser URL: http://localhost:7474/browser/

// Example Cypher Query to find relationships for a specific URL
MATCH (n:Node {url: 'https://example.com'})
-[relationship:parent]-()
RETURN n, relationship;

URL-Graph can also generate a portable JSON map of a local codebase. This path is local-first: it uses the Python standard library, does not call AI services, and does not require Neo4j.

Run it against this repository or any sibling checkout:

python project_map.py . -o project-map.json
python project_map.py ../TorBotApp -o torbotapp-project-map.json

The generated JSON includes:

• directories and files with basic roles and language hints;
• README and Markdown headings for documentation wayfinding;
• containment relationships between directories and files;
• Python import relationships, plus simple JavaScript and TypeScript import hints;
• likely test-to-source relationships when names follow common conventions.

This gives coding agents and local RAG tools a compact starting point for questions such as which files implement a feature, where docs live, and which tests probably cover a module. Neo4j remains a good future export target, but JSON is the lowest-friction format and should stay available.

Example output shape:

{
  "schema_version": 1,
  "summary": {
    "directories": 2,
    "files": 4,
    "edges": 7,
    "languages": ["Markdown", "Python", "YAML"]
  },
  "files": [
    {
      "id": "file:README.md",
      "path": "README.md",
      "language": "Markdown",
      "role": "documentation",
      "headings": ["URL-Graph", "Introduction"]
    }
  ],
  "edges": [
    {
      "source": "dir:.",
      "target": "file:README.md",
      "type": "contains",
      "detail": null
    }
  ]
}