# FenLiu (分流)

> **⚠️ DISCLAIMER / PROVISO**: This project is a **work in progress** with major changes still happening. It is in no way anywhere close to finished and is only borderline useful for actual production use. Expect breaking changes, incomplete features, and significant architectural evolution as development continues.

**Divide the Fediverse content flow**

FenLiu is a web application that monitors Fediverse hashtags, filters spam, allows human review, learns from feedback, and exports quality content for boosting. Inspired by the ancient Chinese Dujiangyan irrigation system (256 BC) that separated silt from water, FenLiu applies 2,300-year engineering wisdom to modern digital content streams.

## Current Status (21 February 2026)

### ✅ Phase 1: Foundation & MVP - COMPLETE
- **Web Application**: PyView-based LiveView interface with real-time capabilities
- **Fediverse Integration**: Fetch posts from Mastodon/Fediverse instances
- **Database**: SQLAlchemy models with SQLite backend
- **REST API**: Full CRUD operations for all entities
- **Testing**: Comprehensive test suite with high coverage

### 🔄 Phase 2: Enhanced Features - IN PROGRESS
- **Spam Scoring**: Basic rule-based system
- **Review Interface**: Manual post review workflow
- **Export Functionality**: FediBooster integration planning

## Quick Start

### Prerequisites
- Python 3.11 or higher
- `uv` package manager (recommended)

### Installation
```bash
# Install dependencies
uv sync -U --all-groups

# Optional: Set up prek hooks
uv run prek install
```

### Running the Application
```bash
# Development mode with auto-reload (simpler)
fenliu --reload --debug

# Alternative development mode
uv run python -m fenliu --reload --debug

# Production mode (simpler)
fenliu --host 0.0.0.0 --port 8000

# Alternative production mode
uv run python -m fenliu --host 0.0.0.0 --port 8000

# See all options
uv run fenliu --help
```

### First Steps
1. Start the server: `fenliu --reload` (or `uv run python -m fenliu --reload`)
2. Open browser: Navigate to `http://localhost:8000`
3. Add a hashtag: Go to Streams page and add a hashtag (e.g., "python")
4. Fetch posts: Click "Fetch" on the hashtag stream
5. Browse posts: View fetched posts on the Posts page

## API Usage

### Basic Examples
```bash
# List all hashtag streams
curl http://localhost:8000/api/v1/hashtags

# Add a new hashtag stream
curl -X POST http://localhost:8000/api/v1/hashtags \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "python", "instance": "mastodon.social", "active": true}'

# Fetch posts for a stream
curl -X POST http://localhost:8000/api/v1/hashtags/1/fetch?limit=20

# Get application statistics
curl http://localhost:8000/api/v1/stats
```

### API Endpoints
- `GET /api/v1/hashtags` - List all hashtag streams
- `POST /api/v1/hashtags` - Create new stream
- `GET/PATCH/DELETE /api/v1/hashtags/{id}` - Stream operations
- `POST /api/v1/hashtags/{id}/fetch` - Fetch posts for stream
- `GET /api/v1/posts` - List posts with filtering
- `GET /api/v1/stats` - Application statistics
- `GET /health` - Health check
- `GET /info` - Application information

## Project Structure
```
fenliu/
├── src/fenliu/
│   ├── __init__.py              # Package definition
│   ├── __main__.py              # CLI entry point
│   ├── main.py                  # PyView application
│   ├── config.py                # Application settings
│   ├── database.py              # Database configuration
│   ├── models.py                # SQLAlchemy models
│   ├── schemas.py               # Pydantic schemas
│   ├── api/                     # REST API endpoints
│   ├── services/                # Business logic
│   └── templates/               # HTML templates
├── tests/                       # Test files
├── pyproject.toml              # Project configuration
└── README.md                   # This file
```

## Testing
```bash
# Run linting and formatting
ruff check src/fenliu/
ruff format src/fenliu/

# Run prek checks
prek run --all-files

# Run full test suite
pytest --cov=src/fenliu tests/
```

## Configuration
Environment variables (via `.env` file):
```bash
# Database configuration
DATABASE_URL=sqlite:///./fenliu.db

# Fediverse settings
DEFAULT_INSTANCE=mastodon.social
API_TIMEOUT=30
MAX_POSTS_PER_FETCH=20
RATE_LIMIT_DELAY=1.0

# Application settings
DEBUG=false
SECRET_KEY=your-secret-key-change-in-production
APP_NAME=FenLiu
APP_VERSION=0.1.0
```

## Development Workflow

### After dependency changes:
```bash
uv sync -U --all-groups
```

### Quick validation:
```bash
prek run --all-files
```

### Full validation before commits:
```bash
nox
```

## Technical Stack
- **Framework**: PyView (Starlette-based LiveView)
- **Database**: SQLAlchemy with SQLite
- **API Client**: minimal-activitypub
- **Async/await**: Full async support for I/O operations
- **Type Hints**: Comprehensive type annotations
- **Validation**: Pydantic for request/response validation
- **Testing**: pytest with async support
- **Linting/Formatting**: ruff with prek hooks
- **Package Management**: uv for fast dependency resolution

## Cultural Context
The name "FenLiu" (分流) means "divide the flow" in Chinese, inspired by the ancient Dujiangyan irrigation system (256 BC). This project applies the same engineering wisdom to digital content streams, separating valuable content from spam and noise.

## Documentation
- [Roadmap](ROADMAP.md) - 5-phase development plan
- [Project Summary](PROJECT_SUMMARY.md) - Overview and next steps
- [LLM System Prompt](LLM_SYSTEM_PROMPT.md) - Development standards

## License
AGPL-3.0 License - See LICENSE file for details.

## Contributing
1. Follow the existing code style (ruff formatted)
2. Add type hints for all public functions
3. Write tests for new functionality
4. Update documentation as needed
5. Run `nox` before submitting changes

---

**Status**: Phase 1 MVP Complete ✅
**Version**: 0.1.0
**Date**: 21 February 2026
**Next Phase**: Enhanced filtering and review interface
**Framework**: PyView (Starlette-based LiveView)
**Architecture**: Async Python with comprehensive type hints
