X Social Graph Explorer

An interactive web application that visualizes social interaction networks around X (Twitter) profiles. Enter a profile URL, and explore the weighted graph of accounts that interact with that profile through mentions, replies, retweets, quotes, and likes.

Features

• 🔍 Profile Input: Enter X profile URLs or handles to explore social graphs
• 📊 Interactive Graph Visualization: 2.5D graph with Cytoscape.js
• 🎨 Weighted Edges: Edge thickness represents interaction intensity
• 🎯 Node Interactions:
  • Hover to see account details
  • Click nodes to view full profile information
  • Highlight connected nodes and edges
• 🎮 Controls:
  • Scroll to zoom
  • Click and drag to pan
  • Arrow keys or A/D to rotate
  • +/- keys to zoom in/out
  • R to reset view
• ⚡ Real-time Data: Fetches interaction data from X API v2
• 📱 Responsive Design: Works on desktop and tablet devices

Architecture

Tech Stack

Backend:

• Node.js with Express.js
• X (Twitter) API v2 integration
• Graph data aggregation and normalization

Frontend:

• React 18 with Vite
• Cytoscape.js for graph visualization
• Tailwind CSS for styling
• Axios for API calls

Project Structure

x-social-graph-explorer/
├── backend/
│   ├── src/
│   │   ├── models/          # Data models (XProfile, GraphNode, etc.)
│   │   ├── services/        # XDataService, GraphBuilderService
│   │   ├── routes/          # API routes
│   │   └── server.js        # Express server
│   ├── package.json
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
├── package.json             # Root workspace config
└── README.md

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• X (Twitter) API v2 Bearer Token

Getting X API Credentials

1. Go to Twitter Developer Portal
2. Create a developer account (if you don't have one)
3. Create a new project/app
4. Generate a Bearer Token with read permissions
5. Save the Bearer Token securely

Installation

1. Clone the repository:

   git clone <repository-url>
   cd x-social-graph-explorer

2. Install dependencies:

   npm run install:all

   Or install manually:

   npm install
   cd backend && npm install
   cd ../frontend && npm install

3. Configure environment variables:

   Copy the example environment file in the backend:

   cp backend/.env.example backend/.env

   Edit backend/.env and add your X API Bearer Token:

   X_API_BEARER_TOKEN=your_bearer_token_here
   PORT=3001
   NODE_ENV=development
   CORS_ORIGIN=http://localhost:5173

Running the Application

Development Mode

From the root directory, run both backend and frontend simultaneously:

npm run dev

Or run them separately:

Terminal 1 - Backend:

npm run dev:backend

Terminal 2 - Frontend:

npm run dev:frontend

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001

Production Build

Build frontend:

cd frontend
npm run build

Start backend:

cd backend
npm start

Usage

1. Open the application in your browser (http://localhost:5173)

2. Enter an X profile URL or handle:

   • Full URL: https://x.com/elonmusk or https://twitter.com/elonmusk
   • Handle: @elonmusk or just elonmusk

3. Click "Generate Graph" to fetch and visualize the social graph

4. Interact with the graph:

   • Hover over nodes to see quick info
   • Click nodes to view detailed information
   • Scroll to zoom in/out
   • Drag to pan around
   • Arrow keys (or A/D) to rotate the graph
   • R key to reset the view

API Endpoints

GET /api/graph

Builds and returns the social graph for a given X handle.

Query Parameters:

• handle (required): X handle without @
• limit (optional): Maximum number of interaction events (default: 100)
• maxResults (optional): Maximum tweets to analyze (default: 10)
• minWeight (optional): Minimum edge weight to include (default: 1)
• maxNodes (optional): Maximum nodes in graph (default: 500)
• minNodeScore (optional): Minimum node interaction score (default: 0)
• minEdgeWeight (optional): Minimum edge weight for filtering (default: 1)

Example:

GET /api/graph?handle=elonmusk&limit=50&maxResults=5

Response:

{
  "rootProfile": {
    "id": "123456",
    "handle": "elonmusk",
    "displayName": "Elon Musk",
    "avatarUrl": "https://..."
  },
  "nodes": [
    {
      "id": "123456",
      "handle": "elonmusk",
      "displayName": "Elon Musk",
      "avatarUrl": "https://...",
      "interactionScore": 100,
      "isRoot": true
    }
  ],
  "edges": [
    {
      "id": "source-target",
      "sourceId": "987654",
      "targetId": "123456",
      "weight": 12
    }
  ]
}

Error Responses:

• 400: Invalid or missing handle
• 403: Profile is private or suspended
• 404: Profile not found
• 503: Rate limit exceeded or upstream API error
• 500: Internal server error

Data Model

Graph Structure

• Nodes: X accounts that interact with the target profile

  • Properties: id, handle, displayName, avatarUrl, interactionScore, isRoot

• Edges: Interaction relationships between accounts

  • Properties: sourceId, targetId, weight (interaction count)

• Interaction Types: reply, mention, retweet, quote, like

Interaction Weights

Different interaction types are weighted differently:

• Reply: 3 points
• Quote: 3 points
• Mention: 2 points
• Retweet: 2 points
• Like: 1 point

Limitations & Notes

1. API Rate Limits: X API has rate limits. If you exceed them, you'll see a "Rate limit exceeded" error. Wait and try again later.

2. Mock Data: The current implementation uses simplified interaction fetching. For production use, you would need:

   • Additional API endpoints for retweets, likes, replies
   • Proper rate limiting handling
   • Caching mechanisms

3. Private Accounts: Private accounts cannot be analyzed without proper authentication.

4. Performance: The graph visualization supports up to a few thousand nodes efficiently. Very large graphs may experience performance issues.

Future Enhancements

• Filter interactions by type (replies, retweets, likes)
• Time-based filters (last 7 days, last 30 days)
• Multiple layout algorithms (force-directed, concentric, hierarchical)
• Export graph as PNG or JSON
• Compare two profiles side-by-side
• True 3D visualization with Three.js
• Real-time graph updates
• Advanced analytics and metrics

Development

Code Structure

Backend Services:

• XDataService: Handles X API calls and data fetching
• GraphBuilderService: Builds and normalizes the social graph

Frontend Components:

• App: Main application component
• ProfileInputForm: Input form for profile URL/handle
• GraphView: Cytoscape.js graph visualization
• NodeDetailsPanel: Side panel showing node details
• StatusBar: Loading and error messages
• Header: Application header

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is provided as-is for educational and demonstration purposes.

Troubleshooting

Backend won't start:

• Check that X_API_BEARER_TOKEN is set in backend/.env
• Ensure port 3001 is not in use
• Check Node.js version (requires >= 18.0.0)

Frontend won't connect to backend:

• Verify backend is running on port 3001
• Check CORS configuration in backend/src/server.js
• Ensure proxy is configured in frontend/vite.config.js

Graph not rendering:

• Check browser console for errors
• Verify API response is valid JSON
• Ensure Cytoscape.js dependencies are installed

Rate limit errors:

• Wait for rate limit window to reset (usually 15 minutes)
• Reduce maxResults parameter
• Consider implementing caching

Support

For issues, questions, or contributions, please open an issue on the repository.

---

Note: This application requires valid X (Twitter) API credentials and is subject to X API terms of service and rate limits.