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.

It was built out of curiosity and is almost complete ai generated using spec-kit with claude code.

## 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`)


## 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

Copyright 2025 Markus Graf <info@markusgraf.ch>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.