2.8 KiB
2.8 KiB
Web App Specific Requirements
Project-Type Overview
Keep v2 is a progressive web application (PWA) built on Next.js 16, designed to deliver a native-like experience in the browser. It prioritizes real-time interactivity for AI features and robust offline capabilities to ensure users can capture thoughts anytime, anywhere, matching the reliability of native note-taking apps.
Technical Architecture Considerations
1. Real-Time AI Interaction (Streaming)
- Behavior: Auto-tagging suggestions will appear live as the user types, utilizing a debounced streaming approach to balance API costs/load with responsiveness.
- Implementation:
- Debounce Strategy: AI analysis triggers after ~1-2 seconds of inactivity or upon detecting sentence completion to avoid analyzing every keystroke.
- UI Feedback: Subtle, non-intrusive UI indicators (e.g., a "thinking" icon or ghost tags) will show when analysis is happening to maintain transparency without distraction.
- Streaming Responses: Tags will populate dynamically, allowing users to click-to-accept immediately.
2. Offline Capability (PWA)
- Requirement: Full PWA support is mandatory. The app must launch and function without an internet connection.
- Strategy:
- Service Workers: Cache app shell and static assets for instant load.
- Local-First Data: Use a robust local database (like RxDB or PouchDB, or optimized browser storage wrappers) to store notes on the client device first, syncing to the backend when online.
- Offline AI Fallback: If the device is offline, AI features (auto-tagging, semantic search) will gracefully degrade (e.g., queueing analysis for when connection is restored, or utilizing small in-browser models if feasible in the future). Basic text search remains functional.
3. Performance & Constraints
- Input Limits: To ensure UI responsiveness and predictable AI processing times, note analysis will be optimized for "standard web page" length (approx. A4 size or ~3000-4000 tokens).
- Handling Long Notes: For notes exceeding this limit, the system will prioritize analyzing the Title, the first paragraph, and the last paragraph (summary effect) to generate tags, ensuring performance doesn't degrade with note length.
- Browser Support: Modern browsers (Chrome, Edge, Firefox, Safari) with a focus on mobile optimization (touch targets, viewport adjustments) for iOS and Android.
Implementation Considerations
- Vercel AI SDK Integration: Leverage
useChatoruseCompletionhooks for managing the streaming AI state seamlessly within React components. - Optimistic UI: All CRUD actions (create, update, delete) must reflect instantly in the UI before server confirmation to ensure the "Zero Friction" feel.