inspiration-app/Docs/Project-Brief.md

---
# **Project Brief: Inspiration Engine**

### Executive Summary

The Inspiration Engine is a private, multimodal creative memory system that unifies images, video, links, and notes into one library. It differentiates on four pillars: end-to-end encryption and user ownership, native automated social ingest, multimodal semantic search with OCR and vision embeddings, and an open path to BYO storage. In short: search by idea, not filename.

**Proof points**

* **Privacy first**: client-side encryption and zero server visibility. Content is encrypted on device before transit and only the user can decrypt it.
* **Native ingest**: background capture from key social sources plus share hooks for any app to minimize manual steps.
* **Multimodal retrieval**: OCR plus vision embeddings for true concept search across images, video, links, and notes.
* **Ownership**: roadmap to Bring-Your-Own-Storage and open standards with export in portable formats.

### **Problem Statement**
* **Current State & Pain Points:** Creatives save inspiration across a fragmented, multimodal ecosystem. This forces a disconnected library of images from Pinterest, videos from TikTok, links from X, and notes in separate apps, with no way to see relationships between media types. When a reference is needed, they must search each platform separately, which breaks creative momentum and causes lost ideas. There is no single place to search by what an asset contains or represents.
* **Why Existing Solutions Fall Short:** Existing tools are siloed by media type. Bookmarking apps handle links, photo managers handle local images, and note apps handle text. None unify and intelligently search a user's entire **multimodal creative memory**. They lack cross-media understanding like text within an image, what a video depicts, or the mood of a song, which are essential for creative discovery.

### **Proposed Solution**
* **Core Concept:** The Inspiration Engine is a private, cross-platform creative memory bank. It provides a single, unified library for images, videos, links, and notes by automatically ingesting content from connected social accounts and other sources. Using intelligent, multimodal search that understands content and meaning, it lets users rediscover assets by idea, not filename or location. It also assists with automatic collections and enables lightweight stylesheets and moodboards in app.
* **Key Differentiators:** Built on **absolute privacy (E2EE)** and **user data ownership (BYO storage)**. Primary technical advantages are a sophisticated **multimodal search engine** (OCR plus vision embeddings) and **native, automated ingestion** from social platforms that removes today’s fragmented, manual workflows.
* **Vision for Success:** Win by addressing the end-to-end inspiration workflow. Establish open standards **OCMS (Open Creative Memory System)** and **CRQL (Creative Retrieval Query Language)** to become the default **private creative operating system**, creating a durable, interoperable ecosystem.

### **Target Users**
* **Primary User Segment: The Individual Creative Professional**
    * **Profile & Behaviors:** Digitally native professionals (designers, illustrators, art directors) active on multiple visual platforms, collecting high volumes of multimodal assets with chaotic, manual workflows.
    * **Needs & Pain Points:** Frictionless capture and rediscovery without context switching. Pain points are lost ideas, wasted time, and not finding what they know they saved.
    * **Goals:** Accelerate from idea to execution. Build stronger moodboards, win pitches, and maintain a reliable creative second brain.
* **Secondary User Segment: The Hobbyist / Personal Memory Curator**
    * **Profile & Behaviors:** Heavy social and camera use for family, travel, and life events. Assets are scattered and disorganized.
    * **Needs & Pain Points:** Automated order for photos and ideas. Pain points are camera-roll chaos and difficulty collating project-specific inspiration.
    * **Goals:** Control and joy in rediscovery. Quickly find all photos of a person or gather every idea for a home project.
* **Secondary User Segment: The Neurodivergent Organizer (ADHD)**
    * **Profile & Behaviors:** Relies on tech to manage object permanence issues. Current capture is screenshots, tabs, and scattered notes.
    * **Needs & Pain Points:** Ultra-low-friction offload to a dependable external memory. Anxiety about forgetting and distraction from noisy searches.
    * **Goals:** Lower cognitive load with a calm, dependable external brain. Confidence that ideas are captured and retrievable in seconds.

### **Goals & Success Metrics**
* **User Success Metrics**
    * **Core Functionality Validation:** Save from at least two sources and successfully rediscover via idea-based or semantic search within seconds.
    * **Effortless Onboarding:** 90% of new users connect a source and save first item within 3 minutes without docs.
    * **“Aha!” Moment:** ≥30% of qualitative feedback mentions rediscovery or surprise.
* **Key Performance Indicators (KPIs)**

| Category | KPI | Target (Initial) | Purpose |
| :--- | :--- | :--- | :--- |
| **Adoption** | Monthly Active Users (MAU) | Growth ≥15% MoM | Track acquisition and sustained usage. |
| **Engagement** | Items Saved per Active User per Week | ≥10 | Measure capture depth. |
| **Retention** | Week 1 / Week 4 Retention | ≥60% / ≥40% | Gauge stickiness. |
| **Core Action Rate** | % of Active Users Performing ≥1 Search per Week | ≥75% | Validate regular semantic search use. |
| **Technical Performance** | Avg. Search Response Time | ≤300ms | Ensure instant, dependable feel. |

### **MVP Scope**
* **Core Features (Must Have)**
    * **Private User Accounts:** Simple signup that provisions a private, end-to-end encrypted data store.
    * **Content Ingestion:** One native social integration (Instagram) plus a universal mobile “Share to Inspiration Engine” hook to prove multi-source capture.
    * **Core Search & Discovery:** Simple UI (search bar + tiled results) powered by a minimal semantic model (CLIP-class visual understanding plus OCR) to deliver the rediscovery magic.
    * **Library & Discovery Tools:** A quick, reactive library view and a simple, artistic “Discovery Grid” for exploration.
    * **Onboarding & Data Management:** Web UI for upload and bulk import, plus a pre-populated example library for instant demo and testing.
    * **Library & Discovery Tools**
        * A quick, reactive library view for browsing saved items.
        * **Discovery Grid**: a simple 9x9 grid with dice-roll rotation, **shipped behind a feature flag**. Enable only after ingest-to-search SLOs are green to keep focus on the core loop.
* **Out of Scope for MVP**
    * Teams and collaboration.
    * Public developer API.
    * Bring-Your-Own-Storage.
    * Full suite of social connectors.
    * Advanced creation tools.
    * Voice-to-Moodboard.
* **MVP Success Criteria**
    * **Quantitative:** Meet or exceed initial KPI targets within 90 days post-launch.
    * **Qualitative:** Consistent feedback that the core problem is solved and the “aha” moment is real.
    * **Technical:** Stable core flows with avg. search time ≤300ms.

### **Post-MVP Vision**
* **Phase 2 Features**
    * Expanded connectivity across major social platforms.
    * Bring-Your-Own-Storage.
    * Initial developer API.
    * Teams and collaboration.
* **Long-term Vision**
    The Inspiration Engine evolves into the default **private creative operating system**. By establishing OCMS and CRQL, it fosters an interoperable ecosystem where users truly own data and can move it freely.
* **Expansion Opportunities**
    * **Platform Expansion:** Native mobile apps, desktop app (Electron), and Chrome extension.
    * **Ecosystem Development:** Open-source OCMS, CRQL, and an MCP server to seed a third-party developer community.
    * **Go-to-Market Expansion:** Targeted campaigns for each segment.
    * **Vertical Expansion:** Education and enterprise knowledge management.

### **Technical Considerations**
* **Platform Requirements**
    * **Target Platforms:** Web app, mobile apps (iOS and Android), desktop app (Electron), and Chrome extension.
    * **Performance Requirements:** Average search response time ≤300ms.
* **Technology Preferences**
    * **Frontend:** Next.js.
    * **Backend:** Next.js API Routes on Cloudflare Workers.
    * **Database:** Cloudflare D1 for structured data, Qdrant for vector search (MVP).
    * **Hosting/Infrastructure:** Cloudflare platform with Wrangler/OpenNext and R2 for object storage.
* **Architecture Considerations**
    * **Repository Structure:** Monorepo to manage multi-platform code.
    * **Service Architecture:** Serverless on Cloudflare. Start with available embedding models and upgrade post-MVP with a documented migration.
    * **Security/Compliance:** **Privacy-by-design** with E2EE as a foundation. Encrypt on device and restrict server visibility to metadata required for operations.
* **Cloudflare primitives we will rely on**
    * **Durable Objects or Queues** for ingestion pipelines, retries, dedupe, and backoff.
    * **R2 multipart resumable uploads** with a **signed URL** pattern for large media.
    * **Edge caching** for thumbnails and search results to reduce perceived latency.
    * **Model slotting** via ONNX-compatible runners and a documented **re-embedding migration plan** when models upgrade.

### **Constraints & Assumptions**
* **Constraints**
    * **Team & Budget:** Bootstrapped, two developers, no dedicated SRE or 24x7 support.
    * **Cost Controls:** Hard caps for inference, storage, and egress with per-MAU budget target ≤$0.30 and auto-throttling when limits are approached.
    * **API & ToS Risk:** Core ingest depends on third-party social APIs that may restrict scopes or change terms.
* **Key Assumptions (Falsifiable Hypotheses)**
    * **User Behavior:** Users feel enough pain to switch.
    * **Technical Feasibility:** A compliant, reliable Instagram connector is buildable and maintainable.
    * **Value Proposition:** Privacy and ownership materially drive adoption.
    * **Monetization:** Freemium can be sustained with future Teams and API plans.
    * **Search Quality:** Semantic search provides clear value over filename and keyword search.
* **Pivot or Kill Signals**
    * Week-4 retention <25% after two iterations.
    * Search relevance <50% by day 30.
    * Ingest success <85% due to ToS or technical limits with no compliant workaround.

### **Risks & Open Questions**
* **Key Risks**
    * **Third-Party API & ToS Dependency:** Platform scope changes could cripple automated ingest.
    * **Market Indifference to Privacy:** Users may prioritize convenience over E2EE.
    * **Cost Overruns & Drift:** Vector search, storage, and egress for media-heavy free tiers can exceed budget.
    * **Key Management Usability:** Lost keys or poor recovery can drive churn and erode trust.
    * **Distribution risk:** App stores and Chrome Web Store may reject or require feature cuts for background ingest, E2EE, or UGC.
    * **Analytics blind spots:** E2EE limits content-level telemetry, slowing relevance tuning without a privacy-safe events plan.
* **Risk Mitigations**
    * **ToS Risk:** Compliance layer with strict scopes, rotating secrets, and a share-sheet fallback. Automated ToS checks.
    * **Vendor Risk:** Abstract vector and blob storage backends from day one.
    * **Cost:** Hard rate limits and background throttling when per-MAU cost SLOs breach.
    * **Key Management:** Passkeys for device binding and printable recovery codes.
    * **Distribution:** Pre-submission reviews, feature flags per store, parallel TestFlight and Chrome Dev builds.
    * **Privacy-safe analytics:** Log timings, sizes, success flags, and client hints only. Add in-product thumbs up or down on search results to collect relevance labels without content inspection.
* **Open Questions**
    * Exact Instagram API scopes and the compliant fallback when scopes are reduced.
    * E2EE key model per-device vs per-user and the final recovery flow when all devices are lost.
    * Specific free-tier caps for uploads, max asset size, and search quotas to control cost.

### **Next Steps**
**Decisions to finalize**

* **E2EE key model**: per-user vs per-device, recovery flow, and future team sharing without re-encrypt storms.
* **Free-tier caps**: uploads per month, max asset size, and search quotas to protect cost per MAU.
* **Data residency and deletion**: supported regions and delete propagation guarantees across R2, Qdrant, and D1.

**Engineering deliverables**

* **Instagram path**: exact API scopes, polling and backoff cadence, and the compliant fallback share-sheet flow if scopes are reduced.
* **Migration story**: importers for **Raindrop**, **Pocket**, and **Eagle** on day one, even if basic.
* **Privacy-safe relevance**: in-product **thumbs up or down** on search results to collect labels without content peeking.

**GTM quick wins**

* **Landing page + import wizard**: “From Pocket or Raindrop to a Private Creative OS” with one-click import.
* **Design-partner program**: recruit **10 studios** with signed feedback cadence tied to KPIs.

### **Appendices**
This Project Brief is supported by the detailed findings in the "Brainstorming Session Results" and "Competitive Analysis Report." Key stakeholder input was provided by the project lead throughout the creation of these documents.