LinkStream — Smart Link Hub with Rules & Analytics 🚀

LinkStream is a fast, modern “link-in-bio” platform with built‑in intelligence. It gives creators and small teams a single public hub of links plus rule-based visibility and integrated analytics so you can control what visitors see and when, and then actually measure how it performs.

Live Deployed Link : https://linkstreamm.vercel.app/

---

Quick status / TL;DR

• Create a public link hub: https://yourdomain.com/{username}
• Add links, reorder them, attach rules (time/device)
• Customize your public page (title, bio, theme, layout, background & profile picture)
• See analytics for visits & clicks — find top performing links
• Built for fast iteration: React (Vite) frontend + Node/Express + MongoDB backend
• Deploy: Frontend → Vercel, Backend → Render

---

Why LinkStream? — The elevator pitch

Most “link-in-bio” apps show static lists. LinkStream adds conditions and analytics:

• Show different links at different times of day (schedule promotions automatically)
• Show mobile-optimized links only to mobile visitors — no manual duplication
• Track visits & clicks to focus effort on top content

Perfect for creators, teachers, bootcamps, small businesses, or hackathon demos that need a data‑backed link hub — fast.

---

🌟 Key Features

🔗 Link Hub Creation

• Add / edit / delete / reorder links
• Unique public URL per user: https://yourdomain.com/{username}
• Page customization: title, bio, theme (dark / light / gradient), layout (centered / cards / minimal)

⚙️ Rule-Based Link Display

• Time-based rules: show a link only between specified hours
• Device-based rules: show optimized link for mobile visitors
• UI-configurable — no code changes required
• Extensible: location-based and performance-driven rules planned

📊 Analytics & Monitoring

• Count page visits and link clicks
• Top & bottom performing links
• Lightweight analytics stored in the DB and surfaced in the dashboard

🔐 Security & Scalability

• JWT authentication
• Rate limiting middleware (prevent abuse)
• MongoDB for persistence
• Modular Express backend for easy feature additions

---

🛠 Tech Stack

Frontend

• React (Vite)
• React Router
• Hosted on Vercel

Backend

• Node.js + Express
• MongoDB (Atlas or self-hosted)
• JWT Auth
• Hosted on Render (or equivalent)

---

Project structure (short)

LinkStream/
├── .vercel/
│   ├── README.txt
│   └── project.json
│
├── README.md
│
├── design/
│   └── LINKSTREAM_UI_DNA.md
│
├── backend/
│   ├── .env.example
│   ├── .gitignore
│   ├── package.json
│   ├── package-lock.json
│   ├── server.js
│   ├── test-db.js
│   │
│   ├── config/
│   │   └── db.js
│   │
│   ├── controllers/
│   │   ├── analyticsController.js
│   │   ├── authController.js
│   │   ├── customizationController.js
│   │   ├── linkController.js
│   │   ├── publicController.js
│   │   └── ruleController.js
│   │
│   ├── middlewares/
│   │   ├── authMiddleware.js
│   │   ├── errorMiddleware.js
│   │   ├── rateLimiter.js
│   │   └── validateRequest.js
│   │
│   ├── models/
│   │   ├── Click.js
│   │   ├── Link.js
│   │   ├── Users.js
│   │   └── Visit.js
│   │
│   ├── routes/
│   │   ├── analyticsRoutes.js
│   │   ├── authRoutes.js
│   │   ├── customizationRoutes.js
│   │   ├── linkRoutes.js
│   │   ├── publicRoutes.js
│   │   └── ruleRoutes.js
│   │
│   └── utils/
│       ├── device.js
│       ├── hash.js
│       ├── jwt.js
│       └── ruleEngine.js
│
└── frontend/
    ├── .env
    ├── .gitignore
    ├── README.md
    ├── eslint.config.js
    ├── index.html
    ├── package.json
    ├── package-lock.json
    ├── vite.config.js
    ├── vercel.json
    │
    ├── public/
    │   ├── vite.svg
    │   ├── image1.webp
    │   ├── image2.webp
    │   ├── image3.webp
    │   ├── image4.webp
    │   ├── image5.webp
    │   ├── image6.webp
    │   ├── image7.webp
    │   ├── image8.webp
    │   ├── image9.webp
    │   ├── image10.webp
    │   ├── image11.webp
    │   ├── image12.webp
    │   ├── image13.webp
    │   ├── image14.webp
    │   └── image15.webp
    │
    └── src/
        ├── main.jsx
        ├── App.jsx
        ├── index.css
        │
        ├── assets/
        │   └── react.svg
        │
        ├── hooks/
        │   └── useRevealOnScroll.js
        │
        └── pages/
            ├── Dashboard.jsx
            ├── PublicLink.jsx
            ├── PublicPage.jsx
            ├── PublicPage.css
            ├── Signup.jsx
            └── login.jsx

---

Environment Variables

Backend (.env)

MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_secret_key
PORT=5000

Frontend (Vercel / build-time)

VITE_API_BASE=https://your-backend-url.onrender.com

Important: Vite inlines import.meta.env values at build time. Add VITE_API_BASE in your Vercel project settings before building, and redeploy (clear cache) to pick up changes.

---

▶️ Running Locally (fastest way)

Backend

# from project root or backend folder
npm install
npm run dev   # nodemon or equivalent
# backend runs: http://localhost:5000

Frontend

cd frontend
npm install
npm run dev
# frontend runs: http://localhost:5173

---

🔁 Deployment (quick checklist)

Backend → Render

1. Connect the GitHub repo
2. Set environment variables on Render dashboard (MONGO_URI, JWT_SECRET, etc.)
3. Deploy

Frontend → Vercel

1. Root directory: frontend
2. Set VITE_API_BASE in Vercel environment variables (production value)
3. Deploy (select “Clear Build Cache” if you changed env vars)

---

🧪 API Overview (useful endpoints)

Auth

POST /api/auth/signup
POST /api/auth/login
GET  /api/auth/me

Links

GET    /api/links
POST   /api/links
PUT    /api/links/:id
DELETE /api/links/:id
PUT    /api/links/reorder

Analytics

POST /api/analytics/visit
POST /api/analytics/click
GET  /api/analytics/summary/:userId

Customization

POST /api/user/customization
GET  /api/user/customization

Public Page

GET /api/public/:username

---

🔧 Quick examples

Save customization (cURL)

curl -X POST "http://localhost:5000/api/user/customization"   -H "Authorization: Bearer <TOKEN>"   -H "Content-Type: application/json"   -d '{"title":"My Page","bio":"Hello world","theme":"dark","layout":"centered","profileImage":"https://i.pravatar.cc/150?u=test"}'

Fetch public page JSON

curl "http://localhost:5000/api/public/johndoe"

---

⚠️ Notes & Practical Tips

• Vercel builds inline env vars — set VITE_API_BASE in Vercel dashboard and redeploy with cache cleared to update the deployed app.
• Production best-practice: use a file-hosting service (Cloudinary / S3) and store URLs in DB instead of base64 blobs.

---

🎯 Usage Flow (user journey)

1. Sign up / LOGIN
2. Open Dashboard
3. Add & reorder links
4. Add rules per link (time/device)
5. Customize public page (title, theme, background, profile)
6. Share public URL
7. Analytics update in real time

---

📈 Future Enhancements (roadmap)

• Location-based rules (geo-targeting)
• Auto-promote highest performing links
• QR code generation for link hubs
• Exportable analytics CSV / PDF
• Offline static public pages (pre-rendered)
• Advanced theme marketplace / templates

---

Contributing

Contributions, issues, and feature ideas are welcome. If you want to help:

1. Fork
2. Create a feature branch
3. Open a PR with a short description

---

Troubleshooting (common dev pain points)

• If login or API calls hang: check VITE_API_BASE and make sure the frontend is hitting the correct backend (local vs production).
• If saving customization yields 413: you likely sent large base64 images — either use URL or increase express.json limit in server.js.
• If deployed frontend doesn’t reflect changes: ensure Vercel has right env vars and redeploy with cache cleared.

---

Licensing & Credits

Built with ❤️ by the LinkStream team — feel free to fork and prototype for hackathons & demos.
(If you reuse code for production, please add proper attribution and secure your secrets.)

---

Contact / Demo request

Open an issue or ping the repo owner for a demo, walkthrough, or to request a feature. Thank you for checking out LinkStream!