RepoFlow: Repository Structure Analysis & Visualisation System

RepoFlow is a developer-intelligence tool designed to demystify complex codebases. It statically parses local repositories, extracts file-import relationships, calculates complexity metrics, and visualizes them on an infinite, interactive 2D canvas. It also integrates with Google Gemini AI to provide instant, plain-English explanations of any file, with local caching to keep API usage cost-free.

---

Features

1. 2D Interactive Architecture Canvas

• Infinite Workspace: Pan, zoom, and physically drag files and folders around.
• Directory Nesting (Sub-flows): Folders render as container frames containing their respective files to preserve physical codebase hierarchy.
• Custom Code Cards: Custom node cards styled per programming language (Python, JavaScript, TypeScript, C/C++, HTML, CSS) with built-in Lines of Code (LoC) size indicators.
• Animated Edges: Import lines show direction (arrows) with neon flowing particles showing dependency direction.
• Hover Highlighting: Hovering over a file card highlights its entire import path (all dependencies and files importing it) while fading out everything else.

2. Static Code Analytics

• Lines of Code (LoC) Tracker: Calculates total lines, empty lines, and comment lines.
• Complexity Heuristic: Scans code files for branching structures (if, for, while, catch) to estimate cyclomatic complexity.
• Function Counts: Counts defined functions per file dynamically.
• Hotspot Detector: The bottom stats bar flags files exceeding 200 lines of code or having high complexity, helping you spot refactoring candidates.

3. Gemini AI Code Explainer & Caching

• Interactive Explanations: Click a file, open the sidebar, and watch Gemini generate a 3-sentence summary of what the code does, typed out with a typewriter animation.
• SQLite Cache Database: Calculates the MD5 hash of the file content. If it matches a cached record, the summary is fetched from cache.db instantly with zero API costs.

4. Graph Image Export

• Auto-Image Saving: Click "Export Image" to download a PNG of the canvas in the browser and automatically write a copy (repo-flow-graph.png) directly inside the codebase folder you scanned!

---

Tech Stack

Layer	Technology	Key Libraries
Frontend	React + Vite + TypeScript	@xyflow/react (React Flow), @dagrejs/dagre, lucide-react, html-to-image
Backend	Python 3.10+ + FastAPI	uvicorn, pydantic, google-genai SDK, python-dotenv
Database	SQLite	Python Standard sqlite3 driver
Styling	Vanilla CSS	Custom dark glassmorphism styling system

---

Repository Structure

repository-visualizer/
├── README.md                 # Project Documentation
├── backend/                  # Python FastAPI Backend
│   ├── app/
│   │   ├── main.py           # FastAPI server endpoints
│   │   ├── parser.py         # Traversal & static import parser
│   │   ├── database.py       # SQLite database configuration
│   │   └── ai_service.py     # Gemini SDK & caching logic
│   ├── .env.template         # Template for environment variables
│   ├── .env                  # local secrets (API Key)
│   ├── inspect_db.py         # Utility script to view SQLite cache
│   ├── requirements.txt      # Python backend packages
│   └── run.py                # Server startup script
└── frontend/                 # React Frontend (Vite)
    ├── package.json          # Node dependencies
    ├── vite.config.ts        # Vite config
    ├── index.html
    └── src/
        ├── main.tsx
        ├── App.tsx           # Dashboard UI and React Flow canvas
        ├── index.css         # Styling system & Glassmorphic variables
        ├── components/
        │   ├── CustomNode.tsx # Files and folders node renders
        │   ├── Sidebar.tsx    # Slide drawer, code preview, AI panel
        │   └── DashboardStats.tsx # Repository summary panels
        └── utils/
            └── layout.ts     # Dagre auto-layout logic

---

Getting Started

To run the project locally, open two terminal windows in VS Code:

1. Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Create and activate a Python virtual environment:

   python -m venv .venv
   Windows PowerShell:
   .venv\Scripts\activate
   Mac/Linux:
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure your API key:
   • Create an .env file and enter your key from Google AI Studio:

     GEMINI_API_KEY=your_gemini_api_key_here

5. Start the FastAPI server:

   python run.py

   The backend will run on http://127.0.0.1:8000 (Docs available at /docs).

2. Frontend Setup

1. Open a second terminal window and navigate to the frontend:

   cd frontend

2. Install npm packages:

   npm install

3. Start the Vite development server:

   npm run dev

4. Open your browser and navigate to: http://localhost:5173/

---

Usage Guide

1. Paste the absolute path of a local project directory into the top search input bar (e.g. C:/Users/chaks/Desktop/repository-visualizer/backend).
2. Click Scan Repository to fetch the graph structure.
3. Click Horizontal Layout or Vertical Layout in the header to tidy up the canvas.
4. Hover over node files to highlight import paths.
5. Click a node to view its lines of code, code preview, and get a Gemini AI summary.
6. Click Export Image to download a PNG layout of your codebase mapping.