TraceOff

Share links without trackers

A comprehensive link cleaning solution that removes tracking parameters and provides clean, shareable links. Built with Flutter for mobile and Node.js/TypeScript for the backend.

🚀 Live Demo • 📱 Mobile App • 🔧 API Documentation • 📖 Documentation

Features

🧹 Link Cleaning

Domain-specific strategies for major platforms (Instagram, YouTube, Twitter, TikTok, etc.)
Generic fallback for unknown domains
Alternative results with different cleaning approaches
Confidence scoring for each cleaned link
Redirect resolution with safety limits

📱 Mobile App (Flutter)

Share sheet integration - clean links directly from other apps
History & favorites - save and organize cleaned links
Settings - customize behavior and appearance
Dark/light theme support
Offline history with local SQLite storage

🖥️ Admin Web UI

Strategy management - create, edit, and manage cleaning rules
Live testing - test links against different strategies
Performance metrics - monitor cleaning performance
Import/export - backup and restore strategies
Secure access - protected by 64-character admin secret

🔧 Backend API (Node.js/TypeScript)

RESTful API with Fastify
Modular strategy engine with pluggable rules
Real-time strategy updates
Comprehensive logging and monitoring

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
Flutter 3.10+ (for mobile development)
Android Studio / Xcode (for mobile development)

Local Development

1. Clone the Repository

git clone https://github.com/aimuhire/traceoff.git
cd traceoff

2. Install Dependencies

# Install root dependencies
npm install

# Install server dependencies
cd server && npm install

# Install mobile dependencies
cd ../mobile && flutter pub get

3. Start Development Servers

# Start both server and mobile (from root)
npm run dev

# Or start individually:
# Server only
cd server && npm run dev

# Mobile only (in another terminal)
cd mobile && flutter run

4. Configure Admin Authentication

The admin UI and strategy management endpoints are protected by a 64-character secret key.

Generate an admin secret:

cd server
node scripts/generate-admin-secret.js

Add to your environment:

# Copy the generated secret to your .env file
echo "ADMIN_SECRET=your-64-character-secret-here" >> .env

Access protected endpoints:

Include the secret in the Authorization header: Bearer your-64-character-secret-here
Or access the admin UI at http://localhost:3000/admin (will prompt for authentication)

5. Access the Application

API Server: http://localhost:3000
Admin UI: http://localhost:3000/admin (requires authentication)
Mobile App: Running on your device/emulator

🚀 Deployment

Vercel Deployment (Recommended)

Fork this repository
Connect to Vercel:
- Go to Vercel Dashboard
- Click "New Project"
- Import your forked repository
- Set the Root Directory to server
- Deploy!

Configure Environment Variables (optional):

LOG_LEVEL=info
CORS_ORIGIN=true
RATE_LIMIT_GENERAL_MAX=100

Manual Deployment

# Build the server
cd server
npm run build

# Deploy to your preferred platform
# The built files are in the 'dist' directory

Mobile App Distribution

# Build for Android
cd mobile
flutter build apk --release

# Build for iOS
flutter build ios --release

API Endpoints

Clean Link

POST /api/clean
Content-Type: application/json

{
  "url": "https://example.com?utm_source=google&utm_campaign=test",
  "strategyId": "optional-strategy-id"
}

Preview Link

POST /api/preview
Content-Type: application/json

{
  "url": "https://example.com?utm_source=google",
  "strategyId": "optional-strategy-id"
}

Strategy Management

GET /api/strategies          # List all strategies
GET /api/strategies/:id      # Get specific strategy
POST /api/strategies         # Create new strategy
PUT /api/strategies/:id      # Update strategy
DELETE /api/strategies/:id   # Delete strategy

Strategy Configuration

Strategies are defined using a flexible JSON schema:

{
  "id": "youtube",
  "name": "YouTube",
  "version": "1.0.0",
  "enabled": true,
  "priority": 100,
  "matchers": [
    {
      "type": "exact",
      "pattern": "youtube.com"
    }
  ],
  "paramPolicies": [
    {
      "name": "v",
      "action": "allow",
      "reason": "Video ID - essential for content"
    },
    {
      "name": "utm_*",
      "action": "deny",
      "reason": "UTM tracking parameters"
    }
  ],
  "pathRules": [
    {
      "pattern": "^/watch\\?.*",
      "replacement": "/watch",
      "type": "regex"
    }
  ],
  "redirectPolicy": {
    "follow": true,
    "maxDepth": 2,
    "timeoutMs": 3000,
    "allowedSchemes": ["http", "https"]
  },
  "canonicalBuilders": [
    {
      "type": "domain",
      "template": "www.youtube.com",
      "required": true
    }
  ]
}

Supported Platforms

Pre-built Strategies

Instagram - Removes tracking while preserving content IDs
YouTube - Keeps video/playlist IDs and playback controls
Twitter/X - Preserves tweet identifiers
TikTok - Maintains video identifiers
Facebook - Keeps content IDs
LinkedIn - Preserves post/article identifiers
Reddit - Maintains subreddit and post IDs
Pinterest - Keeps pin and board identifiers
GitHub - Preserves repository and content paths
Medium - Maintains article identifiers

Generic Strategy

For unknown domains, applies safe generic cleaning:

Follows redirects (with limits)
Removes common tracking parameters
Preserves content-essential parameters
Normalizes URL structure

Development

Server Development

cd server
npm run dev          # Start with hot reload
npm run build        # Build for production
npm test            # Run tests
npm run lint        # Lint code

Mobile Development

cd mobile
flutter run         # Run on connected device
flutter test        # Run tests
flutter analyze     # Analyze code

Monorepo Commands

npm run dev         # Start both server and mobile
npm run build       # Build both projects
npm test           # Test both projects
npm run lint       # Lint both projects

Architecture

Strategy Engine

The core cleaning logic is implemented as a modular strategy engine:

URL Parsing - Parse and validate input URL
Strategy Matching - Find applicable strategy by domain
Redirect Resolution - Follow redirects safely
Parameter Processing - Apply allow/deny rules
Path Rewriting - Apply path transformation rules
Canonicalization - Apply domain/path canonicalization
Alternative Generation - Create alternative cleaned links

Mobile App Architecture

Provider Pattern - State management with Provider
SQLite - Local history storage
Shared Preferences - Settings persistence
Share Intent - OS integration for URL sharing

API Architecture

Fastify - High-performance web framework
TypeScript - Type-safe development
Modular Routes - Clean separation of concerns
Error Handling - Comprehensive error responses

Performance

P95 < 400ms for non-redirect links
Redirect limits - Maximum 10 redirects, 5s timeout
Caching - Strategy caching for known patterns
Efficient parsing - Optimized URL processing

Safety Features

SSRF Protection - Restricted redirect schemes
Input Validation - Comprehensive URL validation
Error Handling - Graceful fallbacks
Rate Limiting - Built-in request limiting
Sanitization - Safe parameter processing

🧪 Testing

Running Tests

# Run all tests
npm test

# Run server tests only
cd server && npm test

# Run mobile tests only
cd mobile && flutter test

# Run with coverage
cd server && npm run test:coverage

Test Coverage

Server: Jest with TypeScript
Mobile: Flutter test framework
Integration: API endpoint testing
E2E: Full workflow testing

📱 Mobile App

Features

Share Integration: Clean links directly from other apps
Offline Mode: Process links locally for privacy
History Management: Save and organize cleaned links
Custom Strategies: Create your own cleaning rules
Dark/Light Theme: Automatic theme switching

Building for Production

# Android APK
flutter build apk --release

# Android App Bundle (for Play Store)
flutter build appbundle --release

# iOS (requires macOS and Xcode)
flutter build ios --release

🔧 API Documentation

Base URL

Production: https://traceoff.vercel.app/api
Development: http://localhost:3000/api

Authentication

Currently, the API is public. Rate limiting is applied per IP address.

Rate Limits

General API: 100 requests per minute
Clean Endpoint: 20 requests per minute
Health Check: 1000 requests per minute

🏗️ Architecture

System Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Mobile App    │    │   Web Admin     │    │   External      │
│   (Flutter)     │    │   (HTML/JS)     │    │   Apps          │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      TraceOff API         │
                    │    (Node.js/Fastify)      │
                    └─────────────┬─────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │    Strategy Engine        │
                    │  (URL Processing Core)    │
                    └───────────────────────────┘

Technology Stack

Frontend: Flutter (Mobile), HTML/CSS/JS (Admin)
Backend: Node.js, TypeScript, Fastify
Database: SQLite (Mobile), In-memory (Server)
Deployment: Vercel (Server), APK/App Store (Mobile)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Run the test suite (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

TypeScript: ESLint + Prettier
Flutter: Dart analysis + flutter analyze
Commits: Conventional Commits format

📄 License

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

Name		Name	Last commit message	Last commit date
Latest commit History 127 Commits
.githooks		.githooks
.github/workflows		.github/workflows
mobile		mobile
resources		resources
scripts		scripts
server		server
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
SETUP.md		SETUP.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

TraceOff

Features

🧹 Link Cleaning

📱 Mobile App (Flutter)

🖥️ Admin Web UI

🔧 Backend API (Node.js/TypeScript)

🚀 Quick Start

Prerequisites

Local Development

1. Clone the Repository

2. Install Dependencies

3. Start Development Servers

4. Configure Admin Authentication

5. Access the Application

🚀 Deployment

Vercel Deployment (Recommended)

Manual Deployment

Mobile App Distribution

API Endpoints

Clean Link

Preview Link

Strategy Management

Strategy Configuration

Supported Platforms

Pre-built Strategies

Generic Strategy

Development

Server Development

Mobile Development

Monorepo Commands

Architecture

Strategy Engine

Mobile App Architecture

API Architecture

Performance

Safety Features

🧪 Testing

Running Tests

Test Coverage

📱 Mobile App

Features

Building for Production

🔧 API Documentation

Base URL

Authentication

Rate Limits

🏗️ Architecture

System Overview

Technology Stack

🤝 Contributing

Development Workflow

Code Style

📄 License

🆘 Support

Getting Help

Community

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages