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