Skip to content
cetkovicaleksaPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

📘 Graph Visualizer

This project was developed as part of the Software Patterns and Components course (Софтверски обрасци и компоненте).


👥 Developers


📖 Project Description

Graph Visualizer is a modular Django-based web application for graph exploration and visualization. It allows users to load graphs from different data sources (JSON, XML, etc.) and visualize them using various visualization plugins (e.g., Simple View, Block View, Tree View, Bird View).

The application is extensible through a plugin architecture, enabling easy integration of new data sources and visualization methods.


🏛️ Architecture

  • API Layer – Defines the core interfaces for data source plugins and visualization plugins.
  • Platform – Hosts the plugin system and coordinates interactions between data, visualization, and UI.
  • Data Source Plugins – Responsible for reading and parsing graph data (e.g., JSON, XML, Steam).
  • Visualizer Plugins – Define how graphs are presented to the user (Main View, Tree View, Bird View).
  • Django Application (graph_explorer) – Provides the web frontend and backend integration.

High-Level Flow:

Data Source Plugin → Platform (API) → Visualizer Plugin → Django UI (Graph Explorer)

📂 Repository Structure

root/
├─ api/                      # Interfaces for plugins (contracts)
├─ platform/                 # Core logic, plugin manager
├─ data_source_plugin_json/  # JSON graph reader plugin
├─ data_source_plugin_xml/   # XML graph reader plugin
├─ data_source_plugin_steam/ # Steam graph reader plugin
├─ simple_visualizer/        # Simple graph visualization plugin
├─ block_visualizer/         # Block-style visualization plugin
├─ graph_explorer/           # Django web application (UI)
└─ docs/                     # Documentation, diagrams, screenshots

⚙️ Installation & Run

Requirements

  • Python 3.10+
  • Django 4+

Setup

# Clone the repo
git clone <repo-url>
cd graph-visualizer

# Setup virtual environment
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Start development server
python manage.py runserver

Application will be available at: http://127.0.0.1:8000/


🚀 Usage

  • Load graph data from JSON or XML via Data Source Plugin.

  • Visualize data using available plugins:

    • Main View – interactive graph with zoom & pan.
    • Tree View – hierarchical representation.
    • Bird View – overview of the entire graph synchronized with main view.
  • Filter, search, and highlight nodes dynamically.

CLI (optional)

# Example: run JSON data source plugin
python manage.py run_plugin data_source_plugin_json --file=graph.json

🔌 Extending with Plugins

To add a new plugin:

  1. Implement the required API interface from /api.
  2. Place the plugin into a new folder at root (e.g., data_source_plugin_csv/).
  3. Register it in the platform for discovery.

🧪 Testing

Run unit tests with:

pytest

or

python manage.py test

⚠️ Known Issues

  • Cycles in graphs may cause recursion in Tree View.
  • Bird View can desynchronize during rapid pan/zoom.
  • Advanced filters are still experimental.

Getting Started with Database Repositories

Our project supports two repository implementations:

  • FileGraphRepository (local file storage)
  • Neo4jGraphRepository (graph database via Docker)

Make sure you have Docker installed. Then start a Neo4j container:

docker run --name neo4j-test   -p 7474:7474 -p 7687:7687   -e NEO4J_AUTH=neo4j/graphit123   -e NEO4J_server_memory_pagecache_size=512M   -e NEO4J_server_memory_heap_initial__size=512m   -e NEO4J_server_memory_heap_max__size=512m   neo4j:5

This will start Neo4j at:

Class Diagram

Graph

classDiagram
    
    class Vertex {
        id : int
        data : Map[str, int | float | bool | date]
    }

    class Edge {
        label : str
        data : Map[str, int | float | bool | date] 
        incident_from(v: Vertex) : bool
        incident_to(v: Vertex) : bool
    }
    Edge "*" --> "1" Vertex : src
    Edge "*" --> "1" Vertex : dest

    Edge <|-- DirectedEdge
    class DirectedEdge {
        ...
        incident_from(v: Vertex) : bool
        incident_to(v: Vertex) : bool
    }

    class Graph {
        <<interface>>
        vertices(): Set[Vertex]*
        edges(): Set[Edge]*

        add_vertex(Vertex)*
        remove_vertex(Vertex)*
        add_edge(Edge)*
        remove_edge(Edge)*
        neighbors(Vertex): Set[Vertex]*
        adjacent(Vertex, Vertex): bool*
        get_vertex(id: int): Optional[Vertex]*
        get_edge(Vertex, Vertex): Optional[Edge]*
        filter_vertices(VertexFilter): Tuple[Tuple[Vertex, ...], Tuple[Edge, ...]]*
    }

    class SetBasedGraph {
        ...
    }

    class VertexFilter {
        <<interface>>
        call(Vertex): bool*
    }

    Graph <|.. SetBasedGraph
    SetBasedGraph "*" --> "*" Edge : edges
    SetBasedGraph "*" --> "*" Vertex : vertices
Loading

Directed edge is incident to one src/dest vertex and incident from the other, while undirected (Edge) is incident to and from both vertices.

Builtin Vertex Filters

---
title: By-attribute filters implementation
---
classDiagram
    direction TB
    
    VertexFilter <|.. Filter
    class Filter {
        <<abstract>>
        attr: str
        value: str | int | float | bool | date
        call(Vertex): bool
        #matches(resolved_value, actual): bool*
    }
    
    Filter <|-- Eq
    class Eq {
        ...
        #matches(resolved_value, actual): bool
    }
    
    Filter <|-- Gt
    class Gt {
        ...
        #matches(resolved_value, actual): bool
    }
    
    Filter <|-- Contains
    class Contains {
        ...
        #matches(resolved_value, actual): bool
    }
    
    %% ...
    note for Filter "Template for by-attribute filters that provides loose comparison."    
Loading

Vertex filter implementations that want to support filter combinations (using &, |, ^ and unary ~) may use CombinableFilterMixin defined in operations.py.

Plugins

Plugins are registered in graphit.datasource and graphit.visualizer groups and must implement DataSourcePlugin and VisualizerPlugin, respectively.

classDiagram
    direction TB
    
    class Plugin {
        <<abstract>>
        name: str*
        identifier: str*
        $config_params: Tuple[ConfigParam]
    }

    class ConfigParam {
        name: str
        required: bool = True
        default: Optional[ConfigParamValueT] = None
        display_name: str = None
        sensitive: bool = False
    }

    class DataSourcePlugin {
        <<abstract>>
        load(**params: ConfigParamValueT): Graph*
    }

    class VisualizerPlugin {
        <<abstract>>
        render(Graph, params...: ConfigParamValueT): str*
    }

    Plugin <|-- VisualizerPlugin
    Plugin <|-- DataSourcePlugin
    
    note for ConfigParam "ConfigParamValueT = str | int | float | date"
    note for Plugin "`config_params` can be class level in python and still be overridable"
Loading

Commands

See commands/, command_execution.py and app.py.

...

classDiagram
class Edge {
  +__init__()
  +src()
  +dest()
  +label()
  +data()
  +data()
  +incident_from()
  +incident_to()
  +__hash__()
  +__eq__()
  +__str__()
  +__repr__()
}
class DirectedEdge {
  +__init__()
  +incident_from()
  +incident_to()
  +__hash__()
  +__eq__()
  +__str__()
  +__repr__()
}
class Graph {
  +vertices()
  +edges()
  +add_vertex()
  +remove_vertex()
  +add_edge()
  +remove_edge()
  +neighbors()
  +adjacent()
  +get_vertex()
  +get_edge()
  +filter_vertices()
}
class SetBasedGraph {
  +__init__()
  +vertices()
  +edges()
  +add_vertex()
  +remove_vertex()
  +add_edge()
  +remove_edge()
  +neighbors()
  +adjacent()
  +get_vertex()
  +get_edge()
  +filter_vertices()
}
class Vertex {
  +__init__()
  +id()
  +data()
  +data()
  +__hash__()
  +__eq__()
  +__str__()
  +__repr__()
}
class VertexFilter {
  +__call__()
}
class Filter {
  +_matches()
  +__call__()
  +_parse_value()
}
class Eq {
  +_matches()
}
class NotEq {
  +_matches()
}
class Gt {
  +_matches()
}
class Gte {
  +_matches()
}
class Lt {
  +_matches()
}
class Lte {
  +_matches()
}
class Contains {
  +__call__()
  +_matches()
}
class Regex {
  +__call__()
  +_matches()
}
class CombinableFilterMixin {
  +__and__()
  +__or__()
  +__xor__()
  +__invert__()
  +__call__()
  +__combine()
}
class SearchFilter {
  +__call__()
}
class ConfigParam {
  +__post_init__()
}
class Plugin {
  +name()
  +identifier()
}
class DataSourcePlugin {
  +load()
}
class VisualizerPlugin {
  +render()
}
class MyDataSource {
  +name
  +identifier
  +config_params
  +load()
}
class SilentHandler {
  +log_message()
}
class JSONYAML2GraphConverter {
  +__init__()
  +convert()
  +_visit_node()
  +_handle_object()
  +_handle_array()
  +_handle_value()
  +_link()
  +visit_object()
  +visit_array()
  +visit_value()
}
class JSONYAMLDataSource {
  +name
  +identifier
  +config_params
  +load()
  +_error_graph()
}
class JSONYAMLSupplier {
  +_id_gen
  +JSON_CT
  +YAML_CT
  +JSON_EXT
  +YAML_EXT
  +_iso_dt_re
  +get_from_url()
  +get_from_file()
  +_loads_json()
  +_loads_yaml()
  +_coerce_json_value()
  +_to_ast()
}
class JSONNode {
  +accept()
}
class ObjectNode {
  +accept()
}
class ArrayNode {
  +accept()
}
class ValueNode {
  +accept()
}
class JSONNodeVisitor {
  +visit()
  +visit_object()
  +visit_array()
  +visit_value()
}
class JSONSupplier {
  +get_from_url()
  +get_from_file()
}
class JSON2GraphConverter {
  +convert()
}
class SteamGraphConverter {
  +convert()
}
class FriendGraphConverter {
  +convert()
}
class SteamDataSource {
  +name
  +identifier
  +config_params
  +__init__()
  +load()
}
class SteamUserNode {
  +to_vertex()
}
class SteamSupplier {
  +BASE_URL
  +fetch()
  +get_username()
  +get_friends()
}
class SimpleConverter {
  +__init__()
  +convert()
}
class BaseGraphBuildingVisitor {
  +__init__()
  +add_vertex()
  +get_vertex()
  +get_vertex_by_id()
  +remove_vertex()
  +add_edge()
  +remove_edge()
}
class GraphBuildingVisitor {
  +visit_processing_instruction()
  +visit_comment()
  +visit_element()
}
class PassVisitorMixin {
  +visit_processing_instruction()
  +visit_comment()
  +visit_element()
}
class AnchorHrefBuildingVisitor {
  +visit_element_a()
}
class XMLDataSource {
  +name
  +identifier
  +config_params
  +__init__()
  +load()
}
class LXMLSupplier {
  +_parsers
  +_supported_mimes
  +get_from_url()
  +get_from_file()
}
class IdGeneratorMixin {
  +_id
  +generate_id()
}
class ProcessingInstructionNodeAdapter {
  +__init__()
}
class CommentNodeAdapter {
  +__init__()
}
class ElementNodeAdapter {
  +__init__()
}
class EchoVisitor {
  +visit_processing_instruction()
  +visit_comment()
  +visit_element()
  +visit_element_a()
}
class XMLNode {
  +accept()
}
class ProcessingInstructionNode {
  +accept()
}
class CommentNode {
  +accept()
}
class ElementNode {
  +accept()
}
class DocumentNode {
  +accept()
}
class XMLNodeVisitor {
  +visit_processing_instruction()
  +visit_comment()
  +visit_element()
  +recursive_operation()
  +recursive_operation()
}
class XMLSupplier {
  +get_from_url()
  +get_from_file()
}
class XML2GraphConverter {
  +convert()
}
class App {
  +__init__()
  +run()
  +stop()
  +command()
}
class Command {
  +execute()
  +undo()
  +__repr__()
}
class BaseGraphCommand {
  +__init__()
  +_graph()
}
class FilterGraphCommand {
  +__init__()
  +execute()
  +undo()
}
class Workspace {
  +__post_init__()
}
class GraphState {
  +__init__()
  +graph()
  +graph()
  +save()
  +reload()
  +delete()
}
class InMemoryGraphState {
  +__init__()
  +graph()
  +graph()
  +save()
  +reload()
}
class DefaultWorkspaceState {
  +__init__()
  +workspace()
  +graph()
  +change_workspace()
  +delete_workspace()
  +save()
  +reload()
}
class WorkspaceState {
  +__init__()
  +workspace()
  +graph()
  +change_workspace()
  +delete_workspace()
  +save()
  +reload()
}
class GraphMemRepository {
  +__init__()
  +get_by_id()
  +save()
  +delete_by_id()
}
class WorkspaceMemRepository {
  +__init__()
  +get_all()
  +get_by_id()
  +save()
  +delete_by_id()
}
class CommandFactory {
  +__call__()
}
class CommandRegistry {
  +__init__()
  +__setitem__()
  +__getitem__()
  +__contains__()
}
class CommandExecutor {
  +UNDO
  +REDO
  +__init__()
  +execute()
  +can_execute()
  +can_undo()
  +can_redo()
  +undo()
  +redo()
}
class PluginService {
  +__init__()
  +load_plugins()
}
class GraphRepository {
  +bootstrap()
  +upsert_workspace()
  +save_graph()
  +load_graph()
  +delete_workspace()
}
class WorkspaceRepository {
  +get_all()
  +get_by_id()
  +save()
  +delete_by_id()
}
class FileGraphRepository {
  +__init__()
  +_ws_dir()
  +bootstrap()
  +upsert_workspace()
  +save_graph()
  +load_graph()
  +delete_workspace()
}
class Neo4jGraphRepository {
  +__init__()
  +close()
  +bootstrap()
  +upsert_workspace()
  +save_graph()
  +load_graph()
  +delete_workspace()
}
class BlockVisualizer {
  +config_params
  +__init__()
  +identifier()
  +name()
  +render()
  +make_json_safe()
  +serialize_vertex_data()
}
class SimpleVisualizer {
  +config_params
  +__init__()
  +identifier()
  +name()
  +render()
}
Edge <|-- DirectedEdge
Graph <|-- SetBasedGraph
CombinableFilterMixin <|-- Filter
Filter <|-- Eq
Filter <|-- NotEq
Filter <|-- Gt
Filter <|-- Gte
Filter <|-- Lt
Filter <|-- Lte
Filter <|-- Contains
Filter <|-- Regex
CombinableFilterMixin <|-- SearchFilter
Plugin <|-- DataSourcePlugin
Plugin <|-- VisualizerPlugin
DataSourcePlugin <|-- MyDataSource
JSONNodeVisitor <|-- JSONYAML2GraphConverter
DataSourcePlugin <|-- JSONYAMLDataSource
JSONNode <|-- ObjectNode
JSONNode <|-- ArrayNode
JSONNode <|-- ValueNode
DataSourcePlugin <|-- SteamDataSource
XML2GraphConverter <|-- SimpleConverter
XMLNodeVisitor <|-- BaseGraphBuildingVisitor
BaseGraphBuildingVisitor <|-- GraphBuildingVisitor
PassVisitorMixin <|-- AnchorHrefBuildingVisitor
BaseGraphBuildingVisitor <|-- AnchorHrefBuildingVisitor
DataSourcePlugin <|-- XMLDataSource
XMLSupplier <|-- LXMLSupplier
ProcessingInstructionNode <|-- ProcessingInstructionNodeAdapter
IdGeneratorMixin <|-- ProcessingInstructionNodeAdapter
CommentNode <|-- CommentNodeAdapter
IdGeneratorMixin <|-- CommentNodeAdapter
ElementNode <|-- ElementNodeAdapter
IdGeneratorMixin <|-- ElementNodeAdapter
XMLNodeVisitor <|-- EchoVisitor
XMLNode <|-- ProcessingInstructionNode
XMLNode <|-- CommentNode
XMLNode <|-- ElementNode
XMLNode <|-- DocumentNode
Command <|-- BaseGraphCommand
BaseGraphCommand <|-- FilterGraphCommand
GraphState <|-- InMemoryGraphState
WorkspaceState <|-- DefaultWorkspaceState
GraphRepository <|-- GraphMemRepository
WorkspaceRepository <|-- WorkspaceMemRepository
GraphRepository <|-- FileGraphRepository
GraphRepository <|-- Neo4jGraphRepository
VisualizerPlugin <|-- BlockVisualizer
VisualizerPlugin <|-- SimpleVisualizer
Loading

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages