PIIK.ME

The open-source link infrastructure for modern businesses.

Real-time analytics, custom domains, and zero latency redirects.

A professional-grade, open-source platform for creating trackable short links, personalized bio pages, and real-time analytics with instant QR code generation — a better alternative to bitly. com

Features • Quick Start • Tech Stack • API Reference • Contributing

📋 Overview

PIIK.ME is a comprehensive link management and analytics platform that empowers marketers, developers, and businesses to create, track, and analyze their URLs with unprecedented insight. Built with modern web technologies and real-time capabilities, it offers everything from URL shortening to personalized bio link pages.

Why PIIK.ME?

🚀 Real-Time Analytics - Watch clicks happen live with WebSocket-powered updates
📱 QR Code Generation - Instantly generate and download customizable QR codes
🎯 Campaign Tracking - Built-in UTM parameter support for marketing attribution
👤 Bio Links - Create stunning personalized bio pages with social links (like Linktree)
✅ Verified Badges - Premium verification system for early adopters
🔒 Secure & Private - Firebase Authentication with security rules
💾 Persistent Storage - All data safely stored in Google Cloud Firestore
⚡ Low Latency - Sub-second analytics updates for immediate insights
🌐 Open Source - Free to use, modify, and deploy for any purpose

✨ Features

Core Capabilities

Feature	Description
URL Shortening	Generate short, memorable links with custom codes
Custom Short Codes	Choose your own vanity URLs with real-time availability checking
Real-Time Analytics Dashboard	Live tracking of impressions, clicks, and shares
QR Code Generation	One-click QR code creation with download functionality
UTM Parameter Management	Add and track campaign parameters (source, medium, campaign, term, content)
Device & Browser Analytics	Detailed breakdown of mobile vs desktop and browser usage
Referrer Tracking	Identify traffic sources and referring websites
Click-Through Rate (CTR)	Automatic calculation and display of conversion metrics
Share Tracking	Monitor social sharing and link distribution
Click History	Chronological log of all link interactions with timestamps

👤 Bio Links (New!)

Create personalized bio pages accessible at piik.me/username:

Custom Profile Pages - Display name, bio, and profile picture
Multiple Link Support - Add unlimited social links with icons
Drag & Drop Ordering - Easily reorder links with drag-and-drop functionality
Live Preview - See changes in real-time while editing
Auto-Save - Changes save automatically without manual intervention
Background Styles - Multiple animated background options including:
- Animated radial gradients
- Mesh gradient effects
- Glassmorphism overlays
Verified Badges - Blue checkmark verification for early adopters
"Under Review" Status - Unverified profiles display review status
Link Previews - Automatic favicon and URL previews for each link
Magnetic Hover Effects - Interactive hover animations on links

🎨 Visual Enhancements

Holographic UI Design - Modern glassmorphism aesthetic
3D Parallax Tilt Effects - Interactive card animations
Animated Mesh Gradients - Dynamic background animations
Magnetic Interactions - Engaging hover states
Responsive Design - Mobile-first UI with modern CSS animations
Loading Animations - Rotating logo on black background

Technical Features

Google Authentication - Secure OAuth login via Firebase Auth
User Dashboard - Centralized view of all created links with quick stats
WebSocket Updates - Real-time analytics via Socket.IO (no page refresh needed)
Firebase Firestore - NoSQL database for scalable data persistence
RESTful API - Comprehensive API for programmatic access
Custom Short Code Validation - Real-time checking with improved UX (300ms debounce)
Firestore Server Timestamps - Proper sorting and display of creation dates
Session Management - Firebase Auth token-based sessions

🛠️ Technology Stack

piik.me is built with modern, production-ready technologies:

Backend

Technology	Purpose
Node.js	JavaScript runtime environment
Express.js	Web application framework
Socket.IO	Real-time bidirectional event-based communication
Firebase Admin SDK	Server-side Firebase operations
nanoid	Secure, URL-friendly unique ID generator
Axios	HTTP client for API requests
QRCode	Server-side QR code generation

Frontend

Technology	Purpose
HTML5	Semantic markup
CSS3	Modern styling with glassmorphism, animations, and transitions
Vanilla JavaScript	Lightweight, no-framework frontend
Firebase SDK	Client-side authentication
QRCode.js	Client-side QR code generation
Three.js	3D graphics and animations
Globe.gl	Interactive 3D globe visualizations
D3 Scale	Data visualization utilities

Database & Authentication

Service	Purpose
Firebase Firestore	NoSQL cloud database
Firebase Authentication	OAuth 2.0 provider (Google Sign-In)

Development Tools

Tool	Purpose
dotenv	Environment variable management
cors	Cross-origin resource sharing
nodemon	Development server with auto-reload

Deployment

Platform	Purpose
Vercel	Serverless deployment with automatic HTTPS

Architecture Highlights

RESTful API - Clean, resource-oriented endpoints
WebSocket Communication - Sub-second analytics updates
JWT Token Authentication - Secure session management
Event-Driven Architecture - Scalable real-time processing
NoSQL Database - Flexible schema for rapid iteration
Client-Server Architecture - Separated concerns with Firebase backend

📦 Dependencies

{
  "dependencies": {
    "axios": "^1.13.2",
    "cors": "^2.8.5",
    "d3-scale": "^4.0.2",
    "d3-scale-chromatic": "^3.1.0",
    "dotenv": "^16.3.1",
    "express":  "^4.18.2",
    "firebase": "^12.4.0",
    "firebase-admin": "^13.5.0",
    "globe.gl": "^2.45.0",
    "nanoid": "^3.3.7",
    "qrcode": "^1.5.4",
    "socket.io":  "^4.6.1",
    "three":  "^0.181.2"
  },
  "devDependencies":  {
    "nodemon": "^3.0.1"
  }
}

🚀 Quick Start

Prerequisites

Node.js v14 or higher (Download)
npm (comes with Node.js)
Google Account (for Firebase setup)
Firebase Project (Create one free)

Installation

Clone the repository

git clone https://github.com/xthxr/piik.me.git
cd piik.me

Install dependencies
```
npm install
```
Set up Firebase
- Create a Firebase project
- Enable Google Authentication
- Create a Firestore database
- Generate service account credentials
- Configure Firestore security rules

Configure environment variables

Create a .env file in the root directory (see .env.example):

PORT=3000
BASE_URL=http://localhost:3000

# Firebase Admin SDK (from service account JSON)
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=your_client_email@your_project. iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Update Firebase web configuration

Edit public/js/firebase-config.js with your Firebase web app credentials.
Start the application
```
npm start
```
For development with auto-reload:
```
npm run dev
```
Access the dashboard

Open your browser and navigate to: http://localhost:3000

📁 Project Structure

The project follows a clean, modular architecture optimized for maintainability and contributor-friendliness:

zaplink/
├── config/               # Configuration files
│   └── firebase.config.js    # Firebase Admin SDK initialization
├── docs/                 # Documentation
│   ├── ARCHITECTURE.md       # System architecture
│   ├── CODE_OF_CONDUCT.md    # Community guidelines
│   ├── FIREBASE_SETUP.md     # Firebase setup guide
│   ├── PROJECT_STRUCTURE.md  # Detailed structure docs
│   └── SECURITY.md           # Security policies
├── public/               # Frontend assets (served statically)
│   ├── assets/              # Icons and images
│   ├── css/                 # Stylesheets
│   ├── js/                  # Client-side JavaScript modules
│   │   ├── app.js           # Main application logic
│   │   ├── auth.js          # Authentication module
│   │   ├── bio-link.js      # Bio link functionality
│   │   ├── qr-generator.js  # QR code generation
│   │   └── firebase-config.js # Firebase client config
│   ├── index.html           # Main dashboard
│   ├── bio.html             # Bio link page
│   └── landing.html         # Landing page
├── scripts/              # Utility scripts
│   └── set-verified-badges.js # Badge management
├── src/                  # Server-side source code
│   ├── middleware/          # Express middleware
│   │   └── auth.middleware.js # Token verification
│   ├── routes/              # API routes (modular)
│   ├── services/            # Business logic
│   │   └── memory.service.js # In-memory storage
│   └── utils/               # Helper functions
│       └── url.utils.js     # URL utilities
├── .env.example          # Environment template
├── CONTRIBUTING.md       # Contribution guide
├── LICENSE               # MIT License
├── package.json          # Dependencies
├── README.md             # This file
├── server.js             # Express server entry point
└── vercel.json           # Deployment config

📖 For detailed information about the project structure, see docs/PROJECT_STRUCTURE.md

🗄️ Data Architecture

piik.me uses Firebase Firestore for scalable, persistent data storage.

Database Collections

`links` Collection

{
  originalUrl: string,      // Full destination URL
  shortCode: string,        // Unique identifier (e.g., "abc123")
  shortUrl: string,         // Complete short URL
  userId: string,           // Firebase Auth user ID
  userEmail: string,        // User's email address
  createdAt: timestamp,     // Server timestamp for proper sorting
  utmParams: {
    source:  string,
    medium: string,
    campaign: string,
    term: string,
    content: string
  }
}

`analytics` Collection

{
  impressions: number,
  clicks: number,
  shares: number,
  clickHistory: [{
    timestamp: timestamp,
    device: string,       // "mobile" or "desktop"
    browser: string,
    referrer: string
  }],
  devices: { mobile: number, desktop: number },
  browsers: { chrome, firefox, safari, edge, other },
  referrers: { "example.com": number, "direct":  number }
}

`bioLinks` Collection

{
  username: string,         // Unique username/slug
  displayName: string,      // Display name
  bio: string,              // Profile bio
  profilePicture: string,   // Profile image URL
  links: [{
    title: string,
    url: string,
    order: number
  }],
  backgroundStyle: string,  // Background theme
  verified: boolean,        // Verification status
  userId: string,
  createdAt: timestamp
}

🔌 API Reference

Authentication

Protected endpoints require a Firebase Auth token:

Authorization: Bearer {firebase-auth-token}

Endpoints

Method	Endpoint	Description
`POST`	`/api/shorten`	Create short link
`GET`	`/api/user/links`	Get user's links
`GET`	`/api/analytics/: shortCode`	Get analytics data
`POST`	`/api/track/impression/: shortCode`	Track impression
`POST`	`/api/track/share/:shortCode`	Track share
`GET`	`/: shortCode`	Redirect (auto-tracks click)
`POST`	`/api/github/bug`	Create GitHub issue

WebSocket Events (Socket.IO)

socket.on('analyticsUpdate', (data) => {
  // { shortCode, impressions, clicks, shares, ...  }
});

🚢 Deployment

Vercel (Recommended)

Install Vercel CLI:
```
npm i -g vercel
```
Deploy:
```
vercel
```
Set environment variables in Vercel dashboard

The repository includes vercel.json for zero-config deployment.

Production Checklist

Update Firestore security rules
Add production domain to Firebase authorized domains
Configure all Firebase credentials as env variables
Set BASE_URL to production domain
Enable HTTPS/SSL
Implement rate limiting
Set up error logging (Sentry)
Configure CDN for static assets

🔒 Security

Implemented Features

✅ OAuth 2.0 via Google (Firebase Authentication)
✅ Server-side token verification
✅ User-specific data isolation
✅ Firestore security rules
✅ HTTPS enforcement (production)

Recommended Additions

// Rate Limiting
const rateLimit = require('express-rate-limit');
app.use('/api/', rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));

// Security Headers
const helmet = require('helmet');
app.use(helmet());

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Contribution Steps

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

Areas for Contribution

🐛 Bug fixes
✨ New features
📝 Documentation
🎨 UI/UX enhancements
⚡ Performance optimizations
🌍 Internationalization (i18n)

📄 License

piik.me is open-source software licensed under the MIT License.

MIT License

Copyright (c) 2024-2025 piik.me

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🙏 Acknowledgments

Built with amazing open-source technologies:

Firebase - Backend infrastructure
Express. js - Web framework
Socket.IO - Real-time communication
Three.js - 3D graphics
Globe.gl - Globe visualizations

⭐ Star this repo if you find it useful!

Made with ❤️ by xthxr

Name		Name	Last commit message	Last commit date
Latest commit History 277 Commits
.github		.github
config		config
docs		docs
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
middleware.js		middleware.js
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js
vercel.json		vercel.json

Uh oh!

License

xthxr/piik.me

Folders and files

Latest commit

History

Repository files navigation

PIIK.ME

The open-source link infrastructure for modern businesses.

Real-time analytics, custom domains, and zero latency redirects.

📋 Overview

Why PIIK.ME?

✨ Features

Core Capabilities

👤 Bio Links (New!)

🎨 Visual Enhancements

Technical Features

🛠️ Technology Stack

Backend

Frontend

Database & Authentication

Development Tools

Deployment

Architecture Highlights

📦 Dependencies

🚀 Quick Start

Prerequisites

Installation

📁 Project Structure

🗄️ Data Architecture

Database Collections

links Collection

analytics Collection

bioLinks Collection

🔌 API Reference

Authentication

Endpoints

WebSocket Events (Socket.IO)

🚢 Deployment

Vercel (Recommended)

Production Checklist

🔒 Security

Implemented Features

Recommended Additions

🤝 Contributing

Quick Contribution Steps

Areas for Contribution

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Contributors 5

Languages

`links` Collection

`analytics` Collection

`bioLinks` Collection

Packages