ergosteur/instaarchive-viewer
1
0
Fork 0
mirror of https://github.com/ergosteur/instaarchive-viewer.git synced 2026-07-04 11:07:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README and GEMINI with Docker usage and new features

Browse Source
This commit is contained in:
ergosteur
2026-03-07 02:50:18 -05:00
parent 6f5021638c
commit c0f3523a9c
3 changed files with 91 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
GEMINI.md
View File

@@ -2,38 +2,40 @@
## 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 allows users to load local archive directories (either official Instagram exports or Instaloader format) and browse posts, reels, and stories.
**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
- **Local Archive Loading:** Uses the `webkitdirectory` API to scan and process local files securely on the client-side.
- **Persistent Caching:** Uses `idb-keyval` (IndexedDB) to cache parsed metadata and server-side media URLs. Subsequent loads of the same archive are instant.
- **Glassy Scanner UI:** A custom-built glassmorphism scanning dashboard with throttled (1s) dynamic blurred backgrounds and a high-density system log.
- **Support for Multiple Formats:** Recognizes official Instagram export structures and Instaloader regex-based naming conventions.
- **Compressed Metadata**: Support for `.json.xz` file decompression using `xz-decompress` (WASM-powered).
- **Dynamic Media Grid**: Customizable grid layouts (1:1 and 3:4 aspect ratios) with adjustable offsets ("bumps") for aesthetic alignment.
- **Story Viewer**: Native-like story experience with segmented progress bars, automated playback, audio controls, and chronological sorting.
- **Auto-Unmute**: Videos default to unmuted when opened in full view for a better user experience.
- **PWA Ready**: Built with `vite-plugin-pwa` for offline capabilities and a standalone application experience.
- **Compressed Metadata:** Support for `.json.xz` file decompression using `xz-decompress` (WASM-powered).
- **Navigation Protection:** Intercepts browser history (`popstate`) and exit events (`beforeunload`) to prevent session loss while maintaining a "Back to Explorer" SPA flow.
- **Production-Ready Docker:** Multi-stage Docker builds using `node:slim` to serve both the Express API and the Vite-built frontend.
### Main Technologies
- **Frontend:** React 19, Vite, TypeScript
- **Styling:** Tailwind CSS (v4)
- **Icons:** Lucide React
- **Animations:** Framer Motion (`motion/react`)
- **Utility:** Date-fns, clsx, tailwind-merge
- **Decompression**: xz-decompress (WASM)
- **Persistence:** IndexedDB (`idb-keyval`)
- **Backend:** Express, tsx (for server-side scanning)
- **Decompression:** xz-decompress (WASM)
## Commands
- `npm install`: Install project dependencies.
- `npm run dev`: Start the local development server on port 3000.
- `npm run build`: Generate the production-ready build in the `dist` folder.
- `npm run preview`: Locally preview the production build.
- `npm run lint`: Execute TypeScript type-checking (`tsc --noEmit`).
- `npm run server`: Start the backend server to scan `./_sample-archives`.
- `npm run lint`: Execute TypeScript type-checking.
## Production Deployment
The project is containerized and available on GHCR. It expects a volume mount at `/archives` containing subdirectories for each user.
### Key Environment Variables
- `PORT`: Server port (default: 3000)
- `ARCHIVES_DIR`: Path to the archives collection (default: /archives)
## Development Conventions
- **Component Architecture:** Functional components with modern hooks.
- **State Management**: React `useState`, `useMemo`, and `useCallback` for optimized performance during large archive scans.
- **File Handling:** Privacy-focused client-side scanning of archive directories.
- **Project Structure:**
- `src/App.tsx`: Main entry point containing application logic and UI components.
- `src/main.tsx`: React DOM mounting.
- `src/index.css`: Global styles and Tailwind imports.
- `vite.config.ts`: Project build and PWA configuration.
- **Username Logic:** The directory name is the definitive source of truth for the account username.
- **State Management:** React `useState`, `useMemo`, and `useCallback` for optimized performance.
- **File Handling:** Uses `RemoteArchiveFile` and `LocalArchiveFile` classes to provide a unified `ArchiveFile` interface for the parser.