Memos

Memos is a high-performance, offline-capable Progressive Web App (PWA) designed for seamless note-taking, task management, and media tracking. Built with React 19, Vite, and Firebase, it combines the fluidity of a native app with the accessibility of the web.

---

Core Features

Smart Notes & Task Management

• Rich Markdown Support: Write notes using standard Markdown formatting (bold, italics, tables, code blocks).
• Interactive Checklists: Checkboxes (- [ ]) automatically sort themselves. Completed items move to the bottom while preserving your document's nested structure and indentation.
• Priority Syntax: Tag tasks with (A), (B), or (C) to prioritize them.
• Dynamic Grid: Masonry grid layout with drag-and-drop reordering on desktop, and a streamlined touch interface on mobile.
• Task Auto-Sync: Incomplete tasks from your specifically tagged "Up Next" note automatically sync into a targeted "Today" note.

Universal Media Tracking

Keep track of Movies, TV Shows, Anime, Video Games, Books, and YouTube Videos all in one place—the "Up Next" Hub.

Tip

Quick Add Search Use the Quick Add FAB to search across all APIs. It features live fuzzy-search, automatic category switching, and smart season parsing (e.g., automatically fetching exactly Season 4 for a TV show).

• Visual Galleries: View your backlog, episode progress (Watching gallery), and scored items (Completed gallery) as high-resolution poster galleries.
• Episode Tracking & Ratings: Dynamically track the episode or chapter you are currently on, and rate finished media using custom emojis.
• Pick For Me: A built-in roulette to help you randomly select what to tackle next from your backlog.
• Smart APIs: Native integrations with TMDB (Movies/Shows/Anime), IGDB (Games), OpenLibrary (Books), and YouTube.

---

Architecture & Performance

Note

Performance is a first-class feature. Memos is heavily optimized to run flawlessly on both desktop browsers and mobile PWAs.

• Offline First: Uses Firebase Firestore's multi-tab IndexedDB persistence. Read and formulate your notes instantly regardless of network conditions.
• Aggressive Code Splitting: The main application bundle is under 250KB. Heavy dependencies (such as @dnd-kit, firebase/messaging, and search engines) are lazy-loaded exactly when needed.
• Zero-Jank Scrolling: Media galleries utilize CSS hardware acceleration (transform: translateZ(0)) and content-visibility for locked 60fps scrolling, even with hundreds of posters.
• Multi-layered Caching: Media metadata is cached first in ultra-fast session RAM, then persistently in Firestore, eliminating duplicate network requests and bypassing API rate limits.

---

Tech Stack

• Frontend: React 19, React Router v7, Vanilla CSS Modules
• Build Tool: Vite 5
• Backend & Auth: Firebase Authentication, Cloud Firestore
• Edge Compute: Cloudflare Workers (Push notification backend & IGDB server-to-server proxy)
• State Management: React Context, optimistic UI updates

---

Local Setup

Prerequisites

1. Node.js 18+
2. A Firebase project with Firestore and Authentication (Email/Password) enabled.
3. API Keys for TMDB and YouTube. IGDB requires the separate Cloudflare proxy deployment.

Installation

1. Clone the repository and install dependencies:

   git clone https://github.com/yourusername/memos.git
   cd memos
   npm install

2. Install dependencies:

   npm install

3. Start the dev server (if developing locally):

   npm run dev

---

Deployment Configuration & Secrets

Important

The application is pre-configured to deploy automatically to GitHub Pages via the .github/workflows/deploy.yml workflow.

Since the frontend requires API keys at build time, you must configure "Repository Secrets" in GitHub:

1. Go to your repository Settings → Secrets and variables → Actions.
2. Add the following secrets:
   • VITE_FIREBASE_API_KEY
   • VITE_FIREBASE_AUTH_DOMAIN
   • VITE_FIREBASE_PROJECT_ID
   • VITE_FIREBASE_STORAGE_BUCKET
   • VITE_FIREBASE_MESSAGING_SENDER_ID
   • VITE_FIREBASE_APP_ID
   • VITE_FIREBASE_MEASUREMENT_ID
   • VITE_FIREBASE_VAPID_KEY
   • VITE_TMDB_READ_TOKEN
   • VITE_IGDB_PROXY_URL
   • VITE_YOUTUBE_API_KEY

Every time you push to main, GitHub Actions will securely inject these secrets into your Vite build.

---

Security

Firestore security rules should be strictly configured to verify authentication. Ensure that users can only read, write, and delete their own private documents (notes, profiles, watch progress, and ratings). Certain generic collections, such as the mediaCache limit external lookups, should be shared and readable by all authenticated users to prevent duplicate API hits.

License

MIT License