Muse-Flow-AI

An intelligent creative writing assistant powered by AI, featuring advanced text processing, semantic search, and multiple AI model integrations for fiction writing.

Edit in StackBlitz next generation editor

Features

Core Writing Features

• Advanced Word Processor: Rich text editing with auto-save and formatting
• AI-Powered Writing Assistance: Multiple AI providers with streaming support
• Semantic Search: Find related content using vector embeddings
• Character Management: Track and develop characters throughout your story
• Story Arc Planning: Organize plot points and narrative structure
• World Building Tools: Create and maintain consistent fictional worlds
• Cross-References: Link related elements across your writing project

AI & Machine Learning

• Multiple AI Providers: Support for OpenAI, Anthropic Claude, and custom models
• Vector Embeddings: ONNX-based local embeddings for semantic search
• Secure AI Integration: Encrypted API key storage and secure communication
• Custom Model Support: Add and manage your own AI models via OpenAI-compatible API

Data & Storage

• Dual Database System: SQLite for relational data, LanceDB for vector storage
• Real-time Sync: Keep your data synchronized across sessions
• Export/Import: Backup and restore your projects
• Offline Support: Continue writing even without internet connection

Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository

   git clone https://github.com/jjgordon89/Muse-Flow-AI.git
   cd Muse-Flow-AI
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   cp server/.env.example server/.env
   

   Edit server/.env with your API keys and configuration.

4. Start the application

   Frontend only:

   npm run dev
   

   API server only:

   npm run dev:server
   

   Full application (frontend + API server):

   npm run dev:full
   

5. Open your browser

   • Frontend: http://localhost:5173
   • API Server: http://localhost:3001

Architecture

Frontend Stack

• React 18 with TypeScript
• Vite for fast development and building
• Tailwind CSS for styling
• Headless UI for accessible components
• Lucide React for icons

Backend Stack

• Express.js API server
• OpenAI-compatible API endpoints
• Rate limiting and security middleware
• CORS support for cross-origin requests

AI & ML Stack

• Hugging Face Transformers for model loading
• ONNX Runtime for local inference
• LanceDB for vector storage
• Apache Arrow for efficient data handling

Database Layer

• SQLite for structured data (src/database/schemas/sqlite-schema.sql)
• LanceDB for vector embeddings
• Sync Manager for data synchronization

Project Structure

├── src/
│   ├── components/          # React components
│   │   ├── ai/             # AI-related components
│   │   ├── common/         # Reusable components
│   │   ├── editor/         # Word processor components
│   │   ├── layout/         # App layout components
│   │   └── sidebar/        # Sidebar panels
│   ├── contexts/           # React contexts
│   ├── database/           # Database managers and schemas
│   ├── hooks/              # Custom React hooks
│   ├── services/           # Business logic services
│   ├── test/              # Test files
│   ├── types/             # TypeScript definitions
│   └── utils/             # Utility functions
├── server/                 # Express API server
│   ├── middleware/         # Express middleware
│   ├── routes/            # API routes
│   ├── services/          # Server services
│   └── validators/        # Request validation
└── docs/                  # Documentation

Available Scripts

Development

• npm run dev - Start frontend development server
• npm run dev:server - Start API server
• npm run dev:full - Start both frontend and API server

Building

• npm run build - Build for production
• npm run preview - Preview production build

Testing

• npm run test - Run unit tests
• npm run test:ui - Run tests with UI
• npm run test:coverage - Run tests with coverage
• npm run test:e2e - Run end-to-end tests

Code Quality

• npm run lint - Lint code
• npm run type-check - Check TypeScript types

API Documentation

The application includes a comprehensive OpenAI-compatible API server. See README-API.md for detailed API documentation including:

• Authentication and security
• Chat completions endpoint
• Custom model management
• Client library integration examples
• Rate limiting and error handling

Testing

Unit Tests

• Vitest for fast unit testing
• Testing Library for React component testing
• Happy DOM for lightweight DOM simulation

Integration Tests

• AI assistant integration tests
• Database integration tests
• Service layer tests

End-to-End Tests

• Playwright for browser automation
• Full application workflow testing

Security Features

• Secure Storage: Encrypted API key storage
• Input Validation: Comprehensive request validation
• Rate Limiting: Protection against abuse
• CORS Configuration: Secure cross-origin requests
• Helmet Security: HTTP security headers
• Error Sanitization: Safe error reporting

Key Components

AI Integration

• EnhancedAIAssistant - Main AI interface
• StreamingAIChat - Real-time AI responses
• SemanticSearch - Vector-based content search

Data Management

• DatabaseManager - Unified database interface
• LanceDBManager - Vector database operations
• SQLiteManager - Relational database operations

Writing Tools

• WordProcessor - Main text editor
• CharactersPanel - Character management
• StoryArcsPanel - Plot organization

Browser Support

• Chrome/Chromium 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Note: Some AI features require modern browser APIs for optimal performance.

Performance

• Virtual Scrolling: Efficient rendering of large documents
• Code Splitting: Lazy loading of components
• Caching: Intelligent caching of AI responses and embeddings
• Debounced Updates: Optimized user input handling
• Memory Management: Proper cleanup of resources

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation as needed
• Follow the existing code style

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• OpenAI for GPT models and API design inspiration
• Anthropic for Claude integration
• Hugging Face for transformer models and tools
• LanceDB for vector database technology
• React Team for the amazing framework

Support

• Issues: GitHub Issues
• Documentation: Check README-API.md for API details
• Discussions: GitHub Discussions

Happy Writing! Let Muse-Flow-AI enhance your creative process with the power of artificial intelligence.