# Saved Posts Tracker (Instagram Saved Posts)

> Self-hosted, resilient Instagram saved posts archiving engine with Netflix-style multi-profile management, checkpoint-based resumable scraping, append-only timeline event auditing, permanent Cloudinary CDN mirroring, and Qdrant vector semantic/face search.

## Core Architecture & Capabilities

### 1. Multi-Profile Management
- Supports multiple independent Instagram account sessions in a single self-hosted instance.
- Each profile maintains isolated cookies, custom user-agents, avatars, and isolated collections in the database.
- Seamless profile switching in the top navigation bar.

### 2. Resumable Checkpoint Scraper
- Paginates through saved posts via authenticated Instagram private endpoints.
- Auto-saves \`checkpointMaxId\` on every page.
- Error taxonomy automatically classifies failures as \`rate_limited\`, \`transient\`, \`auth\`, or \`fatal\`.
- Resumable from the exact checkpoint without re-downloading existing media.

### 3. Append-Only Account Timeline & Event Auditing
- System automatically detects and logs account transformations into \`accountEvents\`:
  - \`username_changed\`: Tracks handle changes from @old to @new with scrape run attribution.
  - \`lost\`: Flags accounts deleted or suspended on Instagram.
  - \`recovered\`: Automatically un-flags accounts that reappear.
  - \`privacy_private\` / \`privacy_public\`: Tracks privacy setting modifications.
  - \`verified_gained\` / \`verified_lost\`: Tracks badge status changes.

### 4. Cloudinary CDN Permanent Media Mirror
- Solves expiring Instagram CDN URLs.
- Automatically mirrors single photos, multi-slide carousel items, and video thumbnails to Cloudinary CDN storage.
- Caches profile pictures with SHA-256 hash change detection.

### 5. AI Vector & Biometric Face Search
- Qdrant vector database integration.
- Multimodal CLIP embeddings (@huggingface/transformers) for natural language visual queries.
- Facial detection and 128-dimensional biometric embeddings (@vladmandic/face-api, TensorFlow.js).

## Tech Stack
- Frontend/Fullstack: Next.js (App Router), React 19, TypeScript, Tailwind CSS, TanStack Query, Lucide Icons.
- Database: Prisma ORM with MongoDB / SQLite support.
- Vector DB: Qdrant.
- Deployment: Docker & Docker Compose.

## Documentation Links
- Quickstart: /docs/quickstart
- Architecture: /docs/architecture
- Scraping Engine: /docs/scraping-engine
- AI Vector Search: /docs/ai-vector-search
- Cloudinary CDN: /docs/cloudinary-sync
- Self-Hosting: /docs/self-hosting
- GitHub: https://github.com/gitnasr/Instagram-Saved-Posts