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:

git clone <repository-url>
cd reklamator

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

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:

sudo systemctl start clamav-daemon  # Linux
# Or brew services start clamav on macOS

6. Initialize the database and create admin user:

python init_admin.py

7. Run the application:

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:

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:

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

import bcrypt
print(bcrypt.hashpw(b'password', bcrypt.gensalt()).decode())

Testing

Run the test suite:

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

pip install -r requirements-dev.txt

Run code quality checks:

# Linting
ruff check .

# Formatting
black .

# Type checking
mypy app/

Production Deployment

See Deployment Guide 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].