🧠 Neural Nexus - Smart Link Hub Platform

Your intelligent link hub platform with powerful analytics, QR code generation, health monitoring, and rule-based routing.

Features • Tech Stack • Installation • Usage • API Documentation

📋 Table of Contents

Overview
Features
Tech Stack
Installation
Usage
Project Structure
API Documentation
Environment Variables
QR Code Generation
Deployment
Contributing
License

🌟 Overview

Neural Nexus is a modern, full-stack link management platform that allows users to create beautiful, shareable link hubs (similar to Linktree) with advanced features like analytics, QR code generation, link health monitoring, and intelligent rule-based routing.

Perfect for:

📱 Social media influencers
💼 Business professionals
🎤 Event organizers
🎨 Content creators
🏢 Marketing teams

✨ Features

🔗 Link Hub Management

Create multiple customizable link hubs
Add, edit, delete, and reorder links
Custom slugs for branded URLs
Enable/disable links without deleting
Rich preview cards with thumbnails

📊 Advanced Analytics

Real-time click tracking
Geographic distribution maps
Device type breakdown (mobile, desktop, tablet)
Browser analytics
Time-series charts for trend analysis
Export data capabilities

🧪 A/B Testing

Create A/B tests for links
Track conversion rates
Statistical significance analysis
Automatic winner selection

👥 Audience Segmentation

Create custom audience segments
Rule-based visitor categorization
Target specific user groups
Behavior-based segmentation

⚙️ Rule Engine

Create conditional routing rules
Time-based redirects
Device-specific routing
Location-based rules
Performance-based optimization

📱 QR Code Generation

Generate QR codes for link hubs
Customizable colors and sizes
High error correction for distance scanning
Download as PNG
Print-ready format
Python script for local IP/ngrok support

🏥 Link Health Monitoring

Real-time link availability checks
Response time tracking
Status categorization (active, slow, broken)
Bulk health checks
Browser header spoofing to bypass bot detection

🎨 User Interface

Modern, responsive design
Dark/Light theme toggle
Mobile-first approach
Smooth animations
Intuitive navigation
Accessible components

🔐 Security

JWT-based authentication
Password hashing with bcrypt
Rate limiting
CORS protection
Input validation
XSS protection

🛠 Tech Stack

Frontend

Framework: React 18.3.1
Build Tool: Vite 6.0.5
Styling: Tailwind CSS 3.4.17
UI Components: Radix UI
Animations: Framer Motion
Charts: Recharts
QR Codes: qrcode.react
HTTP Client: Axios
Routing: React Router (custom implementation)
Notifications: Sonner

Backend

Runtime: Node.js
Framework: Express.js 4.21.2
Database: MongoDB with Mongoose
Caching: Redis
Authentication: JWT (jsonwebtoken)
Security: Helmet, express-rate-limit
Validation: Joi
Password Hashing: bcrypt
HTTP Client: Axios (for link health checks)

Additional Tools

Python: QR code generation with local network support
Git: Version control
npm: Package management

📦 Installation

Prerequisites

Node.js (v16 or higher)
MongoDB (local or cloud)
Redis (optional, for caching)
Python 3.x (for QR generator script)

1. Clone the Repository

git clone https://github.com/Nihar1604/NeuralNexus.git
cd NeuralNexus

2. Backend Setup

cd backend
npm install

Create .env file:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/neural-nexus
JWT_SECRET=your_super_secret_jwt_key_here_change_in_production
JWT_EXPIRES_IN=7d
REDIS_URL=redis://localhost:6379
FRONTEND_URL=http://localhost:5173
NODE_ENV=development

Start MongoDB:

# Windows
mongod

# macOS/Linux
sudo systemctl start mongod

Start Redis (optional):

# Windows
redis-server

# macOS/Linux
sudo systemctl start redis

Start backend:

npm run dev

3. Frontend Setup

cd frontend
npm install

Create .env file:

VITE_API_URL=http://localhost:3000/api

Start frontend:

npm run dev

4. Python QR Generator (Optional)

pip install qrcode[pil]

🚀 Usage

Access the Application

Frontend: http://localhost:5173
Backend API: http://localhost:3000/api

Create an Account

Navigate to the landing page
Click "Register"
Fill in your details
Start creating link hubs!

Create Your First Hub

Log in to your account
Go to "My Link Hubs"
Click "Create New Hub"
Add your links
Share your unique URL or QR code

Generate QR Codes

Option 1: Web Interface

Navigate to "QR Generator"
Select your hub
Customize colors and size
Download as PNG

Option 2: Python Script (for local network access)

# Local WiFi only
python qr_generator.py my-github

# Public access with ngrok
python qr_generator.py my-github --public https://abc123.ngrok.io

# Custom output file
python qr_generator.py my-github myqr.png

Monitor Link Health

Go to "Link Health"
Select a hub
Click "Check All Links"
View status, response times, and issues

View Analytics

Navigate to "Analytics"
Select date range
View clicks, geographic data, devices, and browsers
Export data for reports

📁 Project Structure

NeuralNexus/
├── backend/
│   ├── src/
│   │   ├── config/         # Database and Redis configuration
│   │   ├── controllers/    # Route handlers
│   │   ├── middleware/     # Authentication, validation, rate limiting
│   │   ├── models/         # Mongoose schemas
│   │   ├── routes/         # API routes
│   │   ├── services/       # Business logic
│   │   └── utils/          # Helper functions
│   ├── .env               # Environment variables
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── api/           # API client functions
│   │   ├── app/
│   │   │   ├── components/  # Reusable UI components
│   │   │   └── pages/       # Page components
│   │   ├── context/       # React context providers
│   │   └── styles/        # Global styles
│   ├── .env              # Environment variables
│   └── package.json
├── qr_generator.py       # Python QR code generator
├── setup_public_access.md # Public access setup guide
└── README.md

📚 API Documentation

Authentication

Register

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "username": "johndoe",
  "fullName": "John Doe"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Link Hubs

Get All Hubs

GET /api/hubs
Authorization: Bearer {token}

Create Hub

POST /api/hubs
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "My Links",
  "slug": "my-links",
  "description": "My personal link hub",
  "links": [
    {
      "title": "GitHub",
      "url": "https://github.com/username",
      "isActive": true
    }
  ]
}

Update Hub

PUT /api/hubs/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Updated Title",
  "links": [...]
}

Delete Hub

DELETE /api/hubs/:id
Authorization: Bearer {token}

Check Hub Health

POST /api/hubs/:id/check-health
Authorization: Bearer {token}

Public Access

Get Public Hub

GET /api/public/:slug

Track Click

POST /api/public/:slug/click
Content-Type: application/json

{
  "linkId": "link123",
  "referrer": "https://twitter.com",
  "userAgent": "Mozilla/5.0..."
}

Analytics

Get Hub Analytics

GET /api/analytics/:hubId?startDate=2026-01-01&endDate=2026-01-31
Authorization: Bearer {token}

Segmentation

Get Segments

GET /api/segmentation
Authorization: Bearer {token}

Create Segment

POST /api/segmentation
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Mobile Users",
  "criteria": [
    {
      "field": "device",
      "operator": "equals",
      "value": "mobile"
    }
  ]
}

Rule Engine

Get Rules

GET /api/rules
Authorization: Bearer {token}

Create Rule

POST /api/rules
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Weekend Redirect",
  "hubId": "hub123",
  "isEnabled": true,
  "conditions": [
    {
      "field": "dayOfWeek",
      "operator": "in",
      "value": ["Saturday", "Sunday"]
    }
  ],
  "action": {
    "type": "redirect",
    "value": "https://weekend-special.com"
  }
}

🔧 Environment Variables

Backend (.env)

# Server
PORT=3000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/neural-nexus

# Authentication
JWT_SECRET=your_secret_key_change_in_production
JWT_EXPIRES_IN=7d

# Redis (optional)
REDIS_URL=redis://localhost:6379

# Frontend URL
FRONTEND_URL=http://localhost:5173

Frontend (.env)

# API
VITE_API_URL=http://localhost:3000/api

📱 QR Code Generation

Web-Based Generation

Use the built-in QR Generator page in the application.

Python Script

For generating QR codes that work on local networks or with ngrok:

# Install dependencies
pip install qrcode[pil]

# Generate QR code (auto-detects local IP)
python qr_generator.py my-hub-slug

# Use ngrok for public access
ngrok http 5173
python qr_generator.py my-hub-slug --public https://abc123.ngrok.io

# Custom output file
python qr_generator.py my-hub-slug output.png

See setup_public_access.md for detailed instructions on using ngrok for external access.

🌐 Deployment

Frontend Deployment (Vercel/Netlify)

Vercel

npm install -g vercel
cd frontend
vercel

Netlify

npm install -g netlify-cli
cd frontend
npm run build
netlify deploy --prod --dir=dist

Backend Deployment (Render/Railway)

Render

Create new Web Service
Connect GitHub repository
Set build command: cd backend && npm install
Set start command: cd backend && npm start
Add environment variables

Railway

Create new project
Connect GitHub repository
Add environment variables
Deploy

Database (MongoDB Atlas)

Create free cluster at mongodb.com
Get connection string
Update MONGODB_URI in backend .env

🤝 Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```
Commit your changes
```
git commit -m "Add amazing feature"
```
Push to the branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Development Guidelines

Follow existing code style
Write meaningful commit messages
Add comments for complex logic
Test your changes thoroughly
Update documentation as needed

🐛 Known Issues

Theme toggle requires page refresh on first use (working on fix)
Link health checks may timeout for slow servers (configurable)

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Nihar - @Nihar1604
Smrutikant - @Haze10-stack
Om - @OmKadam

🙏 Acknowledgments

Inspired by Linktree and Bitly
UI components from Radix UI
Icons from Lucide
Charts powered by Recharts

📧 Support

For support, email support@neuralnexus.app or open an issue on GitHub.

Made with ❤️ for Advitya Hackathon 2026

⭐ Star this repo if you find it useful!

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
QUICK_START.md		QUICK_START.md
Readme.md		Readme.md

Latest commit

History

Folders and files

Repository files navigation

🧠 Neural Nexus - Smart Link Hub Platform

📋 Table of Contents

🌟 Overview

✨ Features

🔗 Link Hub Management

📊 Advanced Analytics

🧪 A/B Testing

👥 Audience Segmentation

⚙️ Rule Engine

📱 QR Code Generation

🏥 Link Health Monitoring

🎨 User Interface

🔐 Security

🛠 Tech Stack

Frontend

Backend

Additional Tools

📦 Installation

Prerequisites

1. Clone the Repository

2. Backend Setup

3. Frontend Setup

4. Python QR Generator (Optional)

🚀 Usage

Access the Application

Create an Account

Create Your First Hub

Generate QR Codes

Monitor Link Health

View Analytics

📁 Project Structure

📚 API Documentation

Authentication

Register

Login

Link Hubs

Get All Hubs

Create Hub

Update Hub

Delete Hub

Check Hub Health

Public Access

Get Public Hub

Track Click

Analytics

Get Hub Analytics

Segmentation

Get Segments

Create Segment

Rule Engine

Get Rules

Create Rule

🔧 Environment Variables

Backend (.env)

Frontend (.env)

📱 QR Code Generation

Web-Based Generation

Python Script

🌐 Deployment

Frontend Deployment (Vercel/Netlify)

Vercel

Netlify

Backend Deployment (Render/Railway)

Render

Railway

Database (MongoDB Atlas)

🤝 Contributing

Development Guidelines

🐛 Known Issues

📝 License

👥 Authors

🙏 Acknowledgments

📧 Support

About

Resources

Stars