← Documentation Home 🚀 Try the App

Technical Specification

Version: 1.5.0

1. Project Overview

Goal

A privacy-focused, local web application that analyzes Instagram Data Download (ZIP) files to provide insights into follower relationships without requiring Instagram authentication or sending data to external servers.

Core Features

Privacy Principles

2. Technical Architecture

Frontend Stack

| Technology | Purpose | |————|———| | React 18 | UI framework with hooks and functional components | | TypeScript | Strict mode, zero any types | | Vite | Build tool and development server | | vite-react-ssg | Static Site Generation (page count derived in src/routes.tsx) | | shadcn/ui | Composable UI components built on Radix UI | | Tailwind CSS | Utility-first styling with OKLCH color system | | Zustand | Lightweight state management (<1KB UI state only) | | i18next | Internationalization (10 languages) |

Data Storage & Processing

| Technology | Purpose | |————|———| | IndexedDB v2 | Columnar storage with 40x compression | | FastBitSet.js | Bitwise filtering, 1 bit per account per badge (design target: ~32x vs boolean arrays) | | Comlink | Type-safe Web Worker communication | | TanStack Virtual | Virtual scrolling, renders only the visible window (design target: 60 FPS at 1M+ items) | | Web Workers | Filtering runs off the main thread via Comlink |

Build & Deployment

| Technology | Purpose | |————|———| | Vercel | Hosting with Edge Functions | | vite-plugin-pwa | PWA with 176 precached assets | | @fontsource | Self-hosted fonts (Inter, Plus Jakarta Sans) | | @vercel/og | Dynamic OG image generation |

Testing & Quality

| Technology | Purpose | |————|———| | Vitest | Fast unit testing — npm run test reports the current count | | React Testing Library | Component testing | | @vitest/web-worker | Web Worker testing | | Coverage gates | 85% statements/lines, 80% branches/functions (vitest.config.ts) | | ESLint | Code quality (zero warnings) | | Husky | Git hooks for quality gates |

3. State Management

Zustand Store (<1KB constraint)

interface AppState {
  // Filter state
  filters: Set<BadgeKey>;
  setFilters: (filters: Set<BadgeKey>) => void;

  // Upload state
  uploadStatus: 'idle' | 'loading' | 'success' | 'error';
  uploadError: string | null;
  currentFileName: string | null;

  // File metadata (NOT account data)
  fileMetadata: FileMetadata | null;
  fileDiscovery: FileDiscovery | null;
  parseWarnings: ParseWarning[];

  // Language (persisted; the URL stays the rendering source of truth)
  language: SupportedLanguage;
  setLanguage: (language: SupportedLanguage) => void;

  // Hydration
  _hasHydrated: boolean;
}

Critical Constraints:

Language Detection (URL as Source of Truth)

// src/config/languages.ts
export const SUPPORTED_LANGUAGES = ['en', 'ar', 'de', 'es', 'fr', 'id', 'ja', 'pt', 'ru', 'tr'];
export const RTL_LANGUAGES = ['ar'];

export function detectLanguageFromUrl(): SupportedLanguage {
  const pathname = window.location.pathname;
  const match = pathname.match(/^\/(ar|de|es|fr|id|ja|pt|ru|tr)(\/|$)/);
  return match ? match[1] as SupportedLanguage : 'en';
}

4. IndexedDB v2 Architecture

Database: instagram-tracker-v2

Store Purpose Key
files File metadata registry hash
columns Username/href as packed Uint8Arrays ${hash}:${column}
bitsets Badge presence (1-bit per account) ${hash}:${badge}
timestamps Sparse time data for temporal badges ${hash}:timestamps
indexes Trigram/prefix search indexes (3-day TTL) ${hash}:search

Data Flow

Upload ZIP
    ↓
Parse Worker (Web Worker)
    ├── Extract ZIP (JSZip)
    ├── Parse JSON files
    └── Emit 10k account chunks
    ↓
IndexedDB Service
    ├── Pack columns (Uint8Array)
    └── Update bitsets (FastBitSet)
    ↓
Background: Build search indexes (trigram + prefix)
    ↓
Zustand: uploadStatus = 'success'

Filter Flow (via Web Worker)

FilterChips.onClick(badge)
    ↓
useFilterWorker.filterToIndices(query, filters)
    ↓
Web Worker (filter-worker.ts via Comlink)
    ├── Load bitsets (cached)
    ├── Intersect bitsets (FastBitSet.intersection)
    └── Apply search if query
    ↓
Result: number[] indices
    ↓
TanStack Virtual: render visible items (~20)
    ↓
useAccountDataSource: lazy load accounts by indices

5. Performance Specifications

Benchmarks (1M accounts)

These are design targets, not measurements: no benchmark harness exists in this repository, and the only 1M-scale test (IndexedDBFilterEngine.test.ts) mocks the whole IndexedDB layer and asserts a 500ms ceiling — it measures in-memory bitset iteration, not storage. What IS true: the engine is built and unit-tested against a 1M-account bitset.

Metric Target
Filter (single badge) under 10 ms
Filter (3 badges) under 10 ms
Search (indexed) under 5 ms
Storage under 20 MB
Memory (runtime) under 20 MB
INP under 200 ms
LCP under 2.5 s

Optimization Strategies

6. Internationalization (i18n)

Supported Languages (10)

Language Code RTL Locale
English en — en_US
Español es — es_ES
Русский ru — ru_RU
Deutsch de — de_DE
Português pt — pt_BR
Türkçe tr — tr_TR
Bahasa Indonesia id — id_ID
日本語 ja — ja_JP
العربية ar ✅ ar_SA
Français fr — fr_FR

SSG Architecture

7. File Structure

src/
├── core/                 # Domain logic
│   ├── types.ts          # Core types (Account, BadgeKey, etc.)
│   ├── badges/           # Badge computation logic
│   └── parsers/          # Instagram ZIP parsing
├── lib/                  # Infrastructure
│   ├── store.ts          # Zustand (UI state only!)
│   ├── indexeddb/        # Columnar storage, bitsets
│   ├── filtering/        # BitSet filter engine
│   └── search-index.ts   # Trigram/prefix indexes
├── config/               # Configuration
│   └── languages.ts      # Language config (single source of truth)
├── hooks/                # React hooks
│   ├── useInstagramData.ts
│   ├── useAccountFiltering.ts
│   ├── useAccountDataSource.ts
│   ├── useFilterWorker.ts      # Web Worker hook
│   ├── useLanguageFromPath.ts  # Sync language from URL
│   └── useLanguagePrefix.ts    # Get language prefix for nav
├── workers/              # Web Workers
│   └── filter-worker.ts  # IndexedDBFilterEngine (Comlink)
├── pages/                # SSG page components
│   ├── HomePage.tsx      # / route
│   ├── UploadPage.tsx    # /upload route (the guide opens here)
│   ├── ResultsPage.tsx   # /results route
│   └── ...               # 7 pages total
├── components/           # UI components
│   ├── ui/               # shadcn/ui primitives
│   ├── Layout.tsx        # Root layout (ThemeProvider, Header, Footer)
│   └── *.tsx             # App components
├── locales/              # i18n translations
│   ├── en/               # English
│   ├── es/               # Spanish
│   └── ...               # 10 languages
├── routes.tsx            # SSG route definitions
├── main.tsx              # ViteReactSSG entry point
└── __tests__/            # Tests (mirror structure)

8. Data Schema

Input Format (Instagram Data Download)

connections/followers_and_following/
├── following.json              # Accounts you follow
├── followers_1.json            # Your followers (may be split)
├── close_friends.json          # Close friends list (optional)
├── pending_follow_requests.json    # Pending requests (optional)
├── recently_unfollowed_profiles.json  # Recently unfollowed (optional)
└── restricted_profiles.json    # Restricted accounts (optional)

Core Calculations

9. Browser Compatibility

Supported Browsers

Required Features

10. Security Considerations

Client-Side Security

Data Privacy

11. PWA Configuration

Workbox Strategy

Manifest

{
  "name": "Instagram Unfollow Tracker",
  "short_name": "Instagram Unfollow Tracker",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#000000"
}

12. Development Commands

npm run dev          # Dev server (http://localhost:5173)
npm run build        # Production build (SSG)
npm run test         # Run tests (Vitest)
npm run test:coverage # Tests with 85% threshold
npm run lint:strict  # ESLint (zero warnings)
npm run type-check   # TypeScript validation
npm run code:check   # lint:strict + type-check

This specification reflects v1.5.0 architecture. See CHANGELOG.md for version history.

Last updated:

Documentation Home | Instagram Unfollow Tracker | GitHub | Privacy