Skip to content

README.md

Latest commit

 

History

History
182 lines (143 loc) · 5.66 KB

README.md

File metadata and controls

182 lines (143 loc) · 5.66 KB
Raw

FlowReader - Your Intelligent Reading Companion

Version Status Development License

📚 Personal Use Ready - Core features complete and stable for individual use ⏸️ Expansion Paused - Enterprise and commercialization features on hold 📖 Quick Start: Personal Usage Guide | Self-Test Checklist

An AI-powered reading platform that transforms passive reading into active learning through intelligent conversations, contextual understanding, and smart note-taking.

Features

  • 📚 EPUB Upload & Processing: Drag-and-drop EPUB uploads with intelligent parsing
  • 🔍 Smart Library Management: Search, filter, and organize your reading collection
  • 📖 Enhanced Reading Experience: Customizable reader with progress tracking
  • 🤖 AI Reading Companion: Deep, contextual conversations about your reading content
  • 🧠 Knowledge Enhancement: Real-time explanations of concepts, historical context, and cultural references
  • 💭 Interactive Discussions: Engage in thoughtful debates and analysis with AI
  • 📝 Intelligent Notes System: Automatically capture and organize insights from your reading and AI conversations
  • 📊 Reading Analytics: Track progress and comprehension insights
  • 🎵 Audio Features (Future): High-quality TTS with synchronization capabilities

Tech Stack

  • Frontend: SvelteKit + TypeScript + Tailwind CSS
  • Backend: Vercel Serverless Functions + Supabase
  • Database: PostgreSQL with Row Level Security
  • AI: OpenAI GPT-4 + Embeddings for RAG
  • Queue: Upstash QStash for background processing
  • Storage: Supabase Storage for file assets
  • Audio (Future): Amazon Polly TTS with Speech Marks

Quick Start

Prerequisites

  • Node.js 18+
  • npm or pnpm
  • Supabase account
  • Vercel account (for deployment)

Local Development

  1. Clone and install dependencies

    git clone <repository>
cd FlowReader
npm install

  2. Set up environment variables

    cp .env.example .env.local
# Edit .env.local with your actual values

  3. Set up Supabase

    # Install Supabase CLI
npm install -g supabase

# Initialize and start local Supabase
supabase init
supabase start

# Run migrations
supabase db reset

  4. Start development server

    npm run dev

  5. Run tests

    npm run test
npm run test:e2e

API Testing

Test key endpoints with curl:

# Get signed upload URL
curl -X POST http://localhost:5173/api/upload/signed-url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"fileName": "test.epub", "fileSize": 1024000}'

# Check task status
curl -X GET http://localhost:5173/api/tasks/<task-id>/status \
  -H "Authorization: Bearer <token>"

# Stream AI chat
curl -X POST http://localhost:5173/api/chat/stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"bookId": "<book-id>", "query": "What is this chapter about?"}'

Project Structure

FlowReader/
├── apps/web/                 # SvelteKit frontend application
│   ├── src/
│   │   ├── routes/          # Page routes and API endpoints
│   │   ├── lib/             # Components and utilities
│   │   └── app.html         # HTML template
│   ├── static/              # Static assets
│   └── tests/               # Frontend tests
├── api/                     # Vercel serverless functions
│   ├── _lib/                # Shared utilities
│   ├── _spikes/             # Technical validation prototypes
│   └── [endpoints]/         # API route handlers
├── supabase/
│   ├── migrations/          # Database migrations
│   └── config.toml          # Supabase configuration
├── packages/shared/         # Shared TypeScript types
└── docs/                    # Documentation and user stories

Go/No-Go Verification

Quick Health Check

# Build check
npm run build

# Test suite
npm run test

# Database migrations
supabase db reset

# API endpoints
curl -f http://localhost:5173/api/health

Core Functionality Tests

  • EPUB upload and processing pipeline
  • Reading position persistence across sessions
  • AI chat with contextual responses and knowledge enhancement
  • Intelligent note generation and management
  • Task queue processing and status updates
  • Authentication and authorization flows

Performance Targets

  • TTFT (Time to First Token): < 2 seconds for AI responses
  • AI Response Relevance: > 90% accuracy for contextual questions
  • EPUB Processing: < 30 seconds for files up to 10MB
  • Page Load: < 1 second for library and reader pages
  • Note Generation: < 3 seconds for conversation summaries
  • Reading Position Sync: < 100ms for position updates

Security & Privacy

  • Row Level Security (RLS) for all user data
  • File upload validation and sanitization
  • JWT-based authentication with refresh tokens
  • CORS protection and rate limiting
  • Secure webhook signature verification
  • No logging of user reading content

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

License

MIT License - see LICENSE file for details. EOF < /dev/null