mirror of
https://github.com/ergosteur/instaarchive-viewer.git
synced 2026-07-04 11:07:15 -04:00
b30285fe70
Key changes: - Updated README.md and GEMINI.md with details on background thumbnailing and inter-post preloading. - Documented persistent local archive caching and smart profile fallback features. - Added dist-server/ to .gitignore. - Restored missing feature descriptions and troubleshooting tips in README.
70 lines
3.5 KiB
Markdown
70 lines
3.5 KiB
Markdown
# InstaArchive Technical Documentation
|
|
|
|
## Project Overview
|
|
|
|
**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It supports both local directory loading and self-hosted server modes.
|
|
|
|
### Key Technical Features
|
|
- **Permalinks:** Full synchronization between application state and URL query parameters (`?a=`, `?t=`, `?p=`). Supports deep-linking to archives, tabs, and specific posts. URL parameters are automatically cleaned when navigating back to the archive explorer.
|
|
- **Persistent Caching:** Uses `idb-keyval` (IndexedDB) to cache parsed metadata. Subsequent loads are near-instant.
|
|
- **Metadata:** Caches profile info and post lists for both remote AND local archives.
|
|
- **Thumbnails:** High-res images (>1MiB) and videos have thumbnails generated and cached in IndexedDB with the `thumb_` prefix.
|
|
- **Background Media Processing:**
|
|
- **High-Res Images:** A dedicated Web Worker (`thumbnail-worker.ts`) handles image resizing using `OffscreenCanvas` and `createImageBitmap` to prevent main-thread jank.
|
|
- **Serial Queue:** A memory-safe queue ensures only one high-res image is decoded at a time, preventing Out-of-Memory (OOM) crashes on 50MP+ files.
|
|
- **High-Performance Carousel:** Advanced `PostModal` with:
|
|
- **Inter-Post Preloading:** Preloads the first media of adjacent posts for instant navigation.
|
|
- **Intra-Carousel Preloading:** Intelligently preloads the current carousel's slides.
|
|
- **Seamless Transitions:** Zero-latency slide transitions without "black flashes" between images.
|
|
- **Glassy Scanner UI:** Custom-built glassmorphism scanning dashboard with double-buffering logic to ensure smooth, flicker-free background crossfades during file indexing.
|
|
- **PWA Capabilities:**
|
|
- **Auto-Updates:** Hourly periodic update checks.
|
|
- **Navigation Fix:** `navigateFallbackDenylist` allows direct server access to `/archives/` and `/api/` (enabling "Open in new tab" for original files).
|
|
|
|
### Main Technologies
|
|
- **Frontend:** React 19, Vite 6, TypeScript
|
|
- **Styling:** Tailwind CSS (v4)
|
|
- **Icons:** Lucide React
|
|
- **Animations:** Framer Motion (`motion/react`)
|
|
- **Persistence:** IndexedDB (`idb-keyval`)
|
|
- **Backend:** Express, tsx
|
|
- **Workers:** Web Workers for background image processing.
|
|
|
|
## Architecture
|
|
|
|
### State Management
|
|
- **`useArchiveScanner` Hook:** Centralized logic for parsing and caching. It handles folder-name-to-username detection and "Smart Fallback" profile pictures (using the oldest image if no profile pic is found).
|
|
- **`useThumbnailQueue` Hook:** Manages the serial processing of high-resolution media.
|
|
|
|
### Cache Schema
|
|
```typescript
|
|
interface CacheData {
|
|
name: string;
|
|
isLocal: boolean;
|
|
fileCount: number;
|
|
posts: Post[]; // Cached for all archive types
|
|
stories: Post[];
|
|
profileMetadata: {
|
|
username: string;
|
|
fullName: string;
|
|
bio: string;
|
|
followerCount: number;
|
|
followingCount: number;
|
|
externalUrl: string;
|
|
profilePic: string | null;
|
|
allProfilePics: string[];
|
|
};
|
|
timestamp: number;
|
|
}
|
|
```
|
|
|
|
## Commands
|
|
- `npm install`: Install dependencies.
|
|
- `npm run dev`: Start dev server (Port 3000).
|
|
- `npm run build`: Build frontend (`dist/`) and server (`dist-server/`).
|
|
- `npm run server`: Start production-ready backend.
|
|
- `npm run lint`: Execute TypeScript type-checking.
|
|
|
|
## Production Deployment
|
|
The project is containerized. It expects a volume mount at `/archives` containing subdirectories for each user.
|