owly-news/README.md

# Owly News

Owly News is a modern web application that fetches news articles from various RSS feeds, uses an LLM (Large Language Model) to summarize them, and presents them in a clean, user-friendly interface.

## Features

- Fetches news from configurable RSS feeds
- Automatically summarizes articles using Ollama LLM
- **AI-powered intelligent tagging** with geographic, category, and source tags
- **Advanced multi-criteria filtering** with hierarchical tag support
- Progressive Web App (PWA) support for offline access
- Scheduled background updates
- High-performance Rust backend for optimal resource usage
- Modern Vue.js frontend with TypeScript support
- **Comprehensive analytics** and reading statistics
- **Flexible sharing system** with multiple format options

## Project Structure

The project consists of multiple components:

- **Backend (Rust)**: Primary backend written in Rust using Axum framework for high performance (`backend-rust/`)
- **Backend (Python)**: Legacy FastAPI backend (`backend/`)
- **Frontend**: Modern Vue.js 3 application with TypeScript and Tailwind CSS (`frontend/`)

## Prerequisites

### For Rust Backend (Recommended)
- Rust 1.88.0+
- [Ollama](https://ollama.ai/) for article summarization and tagging
- SQLite (handled automatically by SQLx)

### For Python Backend (Legacy)
- Python 3.8+
- [Ollama](https://ollama.ai/) for article summarization

### For Frontend
- Node.js 22+ and npm
- Modern web browser with PWA support

## Setup

### Rust Backend Setup (Recommended)

1. Navigate to the Rust backend directory:
   ```bash
   cd backend-rust
   ```

2. Create a `.env` file based on the example:
   ```bash
   cp example.env .env
   ```

3. Customize the `.env` file as needed:
   - `DATABASE_URL`: SQLite database connection string
   - `OLLAMA_BASE_URL`: URL for the Ollama service (default: http://localhost:11434)
   - Other configuration options as documented in the example file

4. Run database migrations:
   ```bash
   cargo install sqlx-cli
   sqlx migrate run
   ```

### Frontend Setup

1. Navigate to the frontend directory:
   ```bash
   cd frontend
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

## Running the Application

### Running the Rust Backend

1. Navigate to the Rust backend directory:
   ```bash
   cd backend-rust
   ```

2. Start the backend server:
   ```bash
   cargo run
   ```

   The backend will be available at http://localhost:3000

### Running the Frontend

1. Navigate to the frontend directory:
   ```bash
   cd frontend
   ```

2. Start the development server:
   ```bash
   npm run dev
   ```

   The frontend will be available at http://localhost:5173

## Key Features

### Intelligent Content Organization
- **AI-Powered Tagging**: Automatic classification with geographic, topical, and source tags
- **Hierarchical Filtering**: Multi-level filtering by location (country → region → city), categories, and content types
- **Smart Search**: Advanced filtering with suggestions based on tag relationships and usage patterns
- **Legacy Migration**: Seamless upgrade from simple country-based filtering to comprehensive tag-based system

### Advanced Analytics
- **Reading Statistics**: Track reading time, completion rates, and engagement patterns
- **Content Analytics**: Source performance, tag usage, and trending topics analysis
- **Geographic Insights**: Location-based content distribution and reading preferences
- **Goal Tracking**: Personal reading goals with progress monitoring

### Flexible Article Display
- **Compact View**: Title, excerpt, tags, and action buttons for quick browsing
- **On-Demand Loading**: Full content, AI summaries, and source links as needed
- **Visual Tag System**: Color-coded, hierarchical tags with click-to-filter functionality
- **Reading Status**: Visual indicators for read/unread status and progress tracking

### Enhanced Sharing
- **Multiple Formats**: Text, Markdown, HTML, and JSON export options
- **Custom Templates**: User-configurable sharing formats
- **One-Click Operations**: Copy to clipboard with formatted content
- **Privacy Controls**: Configurable information inclusion in shared content

## Building for Production

### Building the Rust Backend

1. Navigate to the Rust backend directory:
   ```bash
   cd backend-rust
   ```

2. Build the optimized release binary:
   ```bash
   cargo build --release
   ```

   The binary will be available at `target/release/owly-news`

### Building the Frontend

1. Navigate to the frontend directory:
   ```bash
   cd frontend
   ```

2. Build the frontend:
   ```bash
   npm run build
   ```

   The built files will be in the `dist` directory and can be served by any static file server.

## Development

### Code Quality

The project includes comprehensive tooling for code quality:

**Frontend:**
- ESLint with Vue and TypeScript support
- Prettier for code formatting
- Vitest for testing
- TypeScript for type safety
- Oxlint for additional linting

**Backend (Rust):**
- Standard Rust tooling (`cargo fmt`, `cargo clippy`)
- SQLx for compile-time checked SQL queries

### Testing

Run frontend tests:
```bash
cd frontend
npm run test
```

## Configuration

The application uses a comprehensive configuration system via `config.toml`:

- **AI Settings**: Configure Ollama integration for summaries and tagging
- **Display Preferences**: Default views, themes, and UI customization
- **Analytics**: Control data collection and retention policies
- **Filtering**: Smart suggestions, saved filters, and geographic hierarchy
- **Sharing**: Default formats and custom templates

See the example configuration in the project for detailed options.

## Migration from Legacy Systems

The application includes automatic migration tools for upgrading from simpler filtering systems:

- **Country Filter Migration**: Automatic conversion to hierarchical geographic tags
- **Data Preservation**: Maintains historical data during migration
- **Backward Compatibility**: Gradual transition with user control
- **Validation Tools**: Ensure data integrity throughout the migration process

## Future Roadmap

The project is evolving through three phases:
1. **Phase 1**: High-performance Rust backend with advanced filtering and analytics
2. **Phase 2**: CLI application for power users and automation
3. **Phase 3**: Migration to Dioxus for a full Rust stack

See `ROADMAP.md` for detailed development plans and architectural decisions.