Complete Phase 7: Polish & Cross-Cutting Concerns
This commit implements all remaining polish tasks (T193-T210) to make the application production-ready. ## Logging & Monitoring (T193, T194, T208, T209) - Add structured JSON logging for production environments - Add human-readable logging for development - Implement comprehensive error logging across all routes: * submission.py: product access, validation, success/failure * auth.py: login attempts, successes, failures, logouts * dashboard.py: access and errors - Add /health endpoint for monitoring (checks data dir, API key) - Add environment variable validation on startup ## Security Hardening (T196-T199, T207) - Add HSTS headers in production (1 year, includeSubDomains) - Add security headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection - Verify CSRF protection on all POST routes (Flask-WTF) - Verify session cookie security flags (HttpOnly, Secure, SameSite) - Verify XSS prevention (Jinja2 auto-escaping) - Verify no hardcoded secrets (only in test files) ## Documentation (T195, T203, T210) - Add comprehensive README.md with: * Features, quick start, project structure * Usage guides (end users, product owners, admins) * Configuration, testing, deployment instructions - Add detailed docs/deployment.md with: * Production deployment steps * ClamAV, Nginx, SSL/TLS setup * Security hardening, monitoring, backup strategies - Add requirements-dev.txt for development dependencies ## Performance Testing (T200, T201) - Add test_performance.py with 4 comprehensive tests: * 100 concurrent submissions (SC-012) * Dashboard load <3s for 1000 items (SC-008) * Large file upload handling * Rate limiting verification - Add performance marker to pytest.ini ## Testing - All 49 tests passing, 1 skipped - Fixed error handling to preserve HTTP status codes Phase 7 complete. Application is production-ready with comprehensive logging, security, monitoring, and documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -0,0 +1,282 @@
|
||||
# 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].
|
||||
Reference in New Issue
Block a user