Reklamator/README.md

# Reklamator - Anonymous Feedback Platform

Reklamator is a simple, secure anonymous feedback platform that allows users to submit feedback with AI-powered analysis and translation capabilities.

## Features

✅ **Anonymous Feedback Submission** - Users can submit text feedback and/or file attachments without authentication
✅ **Multi-language Support** - Accepts feedback in 50+ languages with automatic language detection
✅ **AI-Powered Analysis** - Automatic categorization, summarization, and translation using Claude AI
✅ **Secure File Handling** - Virus scanning, file type validation, and size limits
✅ **Product Owner Dashboard** - Authenticated access to view, filter, and manage feedback
✅ **Rate Limiting** - Protection against submission abuse
✅ **Privacy-First** - No IP address logging or session tracking for anonymous submissions

## Quick Start

### Prerequisites

- Python 3.11+
- ClamAV (for virus scanning)
- Anthropic API key (for AI analysis)

### Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd reklamator
```

2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Set up environment variables:
```bash
cp .env.example .env
# Edit .env and set:
# - SECRET_KEY (generate with: python -c "import secrets; print(secrets.token_hex(32))")
# - ANTHROPIC_API_KEY (get from https://console.anthropic.com/)
```

5. Start ClamAV daemon:
```bash
sudo systemctl start clamav-daemon  # Linux
# Or brew services start clamav on macOS
```

6. Initialize the database and create admin user:
```bash
python init_admin.py
```

7. Run the application:
```bash
python run.py
```

The application will be available at `http://localhost:5000`

## Project Structure

```
reklamator/
├── app/                      # Application code
│   ├── __init__.py          # Flask app factory with logging and security
│   ├── routes/              # Route blueprints
│   │   ├── submission.py    # Anonymous feedback submission
│   │   ├── dashboard.py     # Product owner dashboard
│   │   ├── auth.py          # Authentication
│   │   └── admin.py         # Admin routes (deferred for POC)
│   ├── services/            # Business logic
│   │   ├── feedback_storage.py  # File-based storage
│   │   ├── ai_analyzer.py       # AI analysis interface
│   │   └── auth.py              # Authentication services
│   ├── models/              # Domain models
│   │   ├── user.py          # User model
│   │   ├── product.py       # Product model
│   │   └── feedback.py      # Feedback model
│   ├── templates/           # HTML templates (plain, no frameworks)
│   └── utils/               # Utilities
│       └── file_validator.py   # File validation and virus scanning
├── data/                    # File-based storage (created at runtime)
│   ├── products/            # Per-product data
│   │   └── {product-id}/
│   │       ├── config.yaml  # Product configuration
│   │       └── feedback/
│   │           └── {feedback-id}/
│   │               ├── metadata.yaml  # Feedback metadata
│   │               ├── content.txt    # Original text
│   │               ├── analysis.md    # AI analysis report
│   │               └── attachments/   # File attachments
│   └── users.yaml           # User database (YAML file)
├── tests/                   # Test suite
│   ├── contract/            # Route contract tests
│   ├── integration/         # Integration tests
│   └── unit/                # Unit tests
├── config/                  # Configuration files
│   ├── development.py       # Development config
│   ├── production.py        # Production config (with HSTS)
│   └── testing.py           # Test config
└── specs/                   # Documentation and specifications
    └── 001-build-an-application/
        ├── spec.md          # Feature specification
        ├── plan.md          # Implementation plan
        ├── tasks.md         # Task breakdown
        └── quickstart.md    # Developer guide
```

## Usage

### For End Users (Anonymous Feedback)

1. Navigate to `/submit/{product-slug}`
2. Enter your feedback in any language (optional if attaching files)
3. Optionally attach up to 3 files (max 10MB each)
4. Submit - your feedback is completely anonymous

### For Product Owners (Dashboard)

1. Navigate to `/login`
2. Log in with your credentials
3. View feedback list at `/dashboard`
4. Filter by category, status, language, or search keywords
5. Click on feedback to view details and AI analysis
6. Update status or manually trigger analysis

### For Administrators

Administrators have access to all products. User and product management is currently done via YAML files (see POC note below).

## Configuration

### Environment Variables

- `SECRET_KEY` - Flask secret key (required in production)
- `ANTHROPIC_API_KEY` - Claude API key for AI analysis
- `DATA_DIR` - Data storage directory (default: `./data`)
- `MAX_CONTENT_LENGTH` - Max upload size in bytes (default: 10MB)
- `CLAMD_SOCKET` - ClamAV socket path (default: `/var/run/clamav/clamd.ctl`)
- `RATE_LIMIT_ENABLED` - Enable rate limiting (default: `true`)
- `RATE_LIMIT_PER_HOUR` - Submissions per hour per IP (default: `10`)

### Managing Products and Users (POC)

**Note**: User Story 4 (Product/Service Registration and Management) has been deferred for the proof-of-concept. Products and users are managed manually via YAML files.

#### Adding a Product

1. Create directory: `data/products/{product-id}/`
2. Create `config.yaml`:
```yaml
product_id: my-product
name: My Product
submission_url_slug: my-product-feedback
owner_language: en
assigned_owner_ids:
  - owner1
status: active
```

#### Adding a User

Edit `data/users.yaml`:
```yaml
- user_id: user1
  username: productowner
  password_hash: $2b$12$...  # Generate with bcrypt
  role: product_owner
  is_active: true
  product_ids:
    - my-product
```

To generate a password hash:
```python
import bcrypt
print(bcrypt.hashpw(b'password', bcrypt.gensalt()).decode())
```

## Testing

Run the test suite:
```bash
# All tests
pytest

# Contract tests only
pytest tests/contract/

# Integration tests only
pytest tests/integration/

# With coverage
pytest --cov=app --cov-report=html
```

## Development

Install development dependencies:
```bash
pip install -r requirements-dev.txt
```

Run code quality checks:
```bash
# Linting
ruff check .

# Formatting
black .

# Type checking
mypy app/
```

## Production Deployment

See [Deployment Guide](docs/deployment.md) for detailed instructions on:
- ClamAV setup
- Nginx reverse proxy configuration
- HTTPS/TLS setup
- Systemd service configuration
- Security hardening

## Security Features

- ✅ CSRF protection on all POST routes (Flask-WTF)
- ✅ Session cookie security flags (HttpOnly, Secure in production, SameSite)
- ✅ HSTS headers in production (1 year, includeSubDomains)
- ✅ Rate limiting on submissions (configurable, default 10/hour)
- ✅ File upload validation (type, size, virus scanning)
- ✅ Complete anonymity (no IP logging for submissions)
- ✅ Structured logging (JSON format in production)
- ✅ Environment variable validation on startup
- ✅ Health check endpoint (`/health`)

## API Endpoints

### Public (No Authentication)
- `GET /submit/{product_slug}` - Display submission form
- `POST /submit/{product_slug}` - Submit feedback
- `GET /health` - Health check endpoint

### Authenticated (Product Owners)
- `GET /login` - Login page
- `POST /login` - Process login
- `GET /logout` - Logout
- `GET /dashboard` - Feedback list with filters
- `GET /feedback/{id}` - Feedback detail
- `POST /feedback/{id}/status` - Update feedback status
- `POST /feedback/{id}/analyze` - Manually trigger AI analysis
- `GET /feedback/{id}/attachment/{filename}` - Download attachment

## Technology Stack

- **Backend**: Python 3.11+ with Flask 3.0
- **AI**: Anthropic Claude API
- **Security**: ClamAV, Flask-WTF (CSRF), Flask-Limiter (rate limiting)
- **Authentication**: Flask-Login with bcrypt password hashing
- **Storage**: File-based (YAML + Markdown, no database)
- **Testing**: pytest with contract and integration tests
- **Frontend**: Plain HTML with minimal inline CSS (no frameworks)

## License

[Add your license here]

## Contributing

[Add contribution guidelines here]

## Support

For issues, please open a GitHub issue or contact [your support email].