Graphly

Master Graph Algorithms: Learn, Visualize, Solve.

---

📖 About The Project

Graphly is an all-in-one platform designed to help students and developers master graph algorithms. Whether you are a beginner trying to understand BFS or an advanced coder practicing for interviews, Graphly provides the tools you need.

The platform combines theoretical articles, interactive visualizations, a "LeetCode-style" coding judge, and a structured roadmap - all powered by an intelligent AI assistant.

---

🚀 Key Features

Graphly is divided into four main modules designed to guide you from novice to expert.

1. Learn

Grasp the theory before diving into code.

• Concise Articles: Simple, easy-to-read explanations of complex graph concepts.
• Quizzes: Test your knowledge immediately after reading to ensure retention.

📖 Conceptual Clarity

Clean, distraction-free articles that break down complex graph theories into simple terms. Includes snippets of code and diagrams.

📝 Immediate Reinforcement

Test your understanding right after reading. Interactive quizzes ensure you've grasped the core concepts before moving to the Visualization phase.

2. Visualize

The heart of Graphly. Don't just read code - watch it run.

• Interactive Visualization: Nodes are fully draggable. Rearrange the graph layout to better understand complex connections. You can freely move, zoom in, and zoom out of the graph area to better explore connections and handle larger networks.
• Step-by-Step Execution: Step through algorithms (BFS, DFS, Dijkstra, etc.).
• Dynamic Coloring: Watch nodes and edges change color in real-time to visually track the algorithm's progress.
• Step-by-Step Navigation: Control the flow via UI buttons or use keyboard arrows (← / →) to step backward and forward through the execution.
• Live Data Structures: See exactly what is inside the Queue, Stack, or Priority Queue at every step.
• Reference Code: Sample code is displayed alongside the graph to help you correlate the visual steps with standard algorithmic logic.
• Custom Graphs: Edit the graph using a simple text syntax.

Example: Step-by-Step Executing DFS Algorithm

3. Solve (Powered by Judge0)

Practice makes perfect. A built-in coding environment similar to LeetCode.

• Language Support: Write solutions in Python using the embedded Monaco Editor.
• Two Execution Modes:
  • ▶️ Run: Test your code against local, visible test cases to debug logic.
  • ✅ Submit: Validate your solution against hidden database test cases.
• AI Performance Insights: Upon a successful submission (Accepted), GraphlyAI automatically analyzes your code. It provides a detailed breakdown of Time & Space Complexity and offers actionable tips to further optimize or refactor your solution.
• Test Case Feedback: Clear JSON-based feedback on pass/fail status.

👨‍💻 The Coding Workspace

The problem interface features a full-screen description, test case manager, and a Monaco-based Python editor. Users can verify logic against local test cases before submitting.

🤖 Submission & AI Insights

After a successful submission, Judge0 returns runtime stats. Simultaneously, GraphlyAI analyzes the code to explain Time/Space complexity and suggests optimizations.

4. Quest

Embark on a structured journey to master graph algorithms. The Quest is a curated learning path that takes you from the fundamental graph algorithms to advanced.

5. Roadmap

A structured learning tree to guide your journey from basic traversals to advanced algorithms.

• Dependency Tree: Shows the logical order of learning (e.g., learn DFS before Topological Sort).
• Curated Problems: Links to example problems from top coding platforms for each topic.

🌳 The Big Picture

A visual dependency tree representing the optimal learning path.

🔗 Curated Practice Problems

Click on any node (e.g., "Topological Sort") to reveal a curated list of high-quality problems from platform like LeetCode, specific to that topic.

---

🎮 Challenge Mode

Think you've mastered the logic? Put your skills to the test in Challenge Mode (Quest section). Instead of just watching the algorithm run, you become the processor.

How it works:

• Active Execution: The app prompts you for the next step in an algorithm (e.g., "Which vertex is visited next in BFS?").

• Instant Feedback:

  • Blue: Correct move! The algorithm continues to the next step.

  • Red: Incorrect. The node flashes red to indicate a logic error, helping you identify gaps in your understanding.

• Track Progress: Complete the visualization without mistakes to prove your algorithmic expertise.

• Lastly correctly seleted node is marked with the blue background and white border.

Example: Incorrect move in Challenge Mode (node turns red) during a recursive DFS.

🤖 GraphlyAI Assistant

Stuck? GraphlyAI is available on every page.

• Context-Aware: Select any text on the screen (article, code, or problem description) and click "Ask GraphlyAI" for specific help.
• Coding Helper: Ask for hints, time complexity analysis or debugging help.
• Smart Context Injection: No need to copy-paste context every time. The helper automatically injects for example your current graph structure, pseudocode and visualization history into the chat context.

Example: GraphlyAI analyzing an undirected graph to identify an Euler Path.

---

🛠️ Graph Syntax

In the Visualize section, you can create your own graphs using a simple text-based format.

Format: Source--Target:Weight

Examples:

• 1--2:5 (Connects node 1 to node 2 with weight 5)
• A--B:10 (Connects node A to node B with weight 10)

Just type the relationships, and the graph renders instantly!

---

🏗️ Architecture & Tech Stack

• Frontend\Backend: React & Next.js & TypeScript & Tailwind & D3.js & React Flow
• Database\Cache\ORM: MySQL & Redis & Prisma
• Code Execution: Judge0 (Self-hosted via Docker)
• AI Integration: Google Generative AI (Gemini)
• Infrastructure: Docker & Docker Compose

---

🏁 Getting Started

To run Graphly locally, you need Docker installed.

1. Clone the repository

   git clone https://github.com/Lukas249/Graphly.git
   cd graphly

2. Set up Environment Variables

   Create a .env file in the root directory:

   GOOGLE_AI_STUDIO_API_KEY=api key from https://aistudio.google.com/
   GOOGLE_AI_STUDIO_MODEL_NAME=gemini-3-flash-preview
   
   NEXT_PUBLIC_BASE_URL=http://graphly-web:3000
   NEXT_PUBLIC_JUDGE0_URL=http://judge0-server:2358
   
   REDIS_URL=redis://graphly-redis:6379
   
   MYSQL_USER=user
   MYSQL_PASSWORD=password
   MYSQL_DATABASE=nextjs_db
   
   DATABASE_URL=mysql://user:password@graphly-mysql:3306/nextjs_db

3. Run with Docker Compose

   This will start the all needed services.

   npm run docker-prod

   Note: If the startup fails or you encounter errors, you must clean up the old containers and volumes before retrying to ensure a clean state. Run the following command:

   npm run docker-down

4. Access the App

   Open http://localhost:3000 (or your configured port) in your browser.

Troubleshooting: Line Ending Errors ($'\r': command not found)

If you see errors like /judge0.conf: line 14: $'\r': command not found, your configuration file has Windows-style line endings (CRLF). You must convert it to Unix-style (LF) for Docker to read it correctly.

Easiest Fix:

1. Open the file in VS Code.
2. Look at the status bar in the bottom-right corner of the window.
3. Click on CRLF and select LF from the menu.
4. Save the file.

🔧 Judge0 Configuration

The judge0/judge0.conf file handles the configuration for the code execution engine. Crucially, it defines authentication credentials:

• REDIS_PASSWORD
• POSTGRES_PASSWORD

Note: By default, these are set to password.

It also sets the correct hostnames for Docker service discovery:

• REDIS_HOST=judge0-redis
• POSTGRES_HOST=judge0-db

Important: These hostnames must match the service names defined in your judge0/docker-compose.yml file exactly.