Reklamator/specs/001-build-an-application/research.md

# Research: Anonymous Feedback Platform (Reklamator)

**Branch**: `001-build-an-application` | **Date**: 2025-10-15

This document resolves all NEEDS CLARIFICATION items identified in the Technical Context section of plan.md.

## 1. AI Integration Approach

### Decision: Pluggable AI provider interface with Claude as default

**Rationale**:
- User input specifies "we use claude but it can be any other service as well"
- Designing for extensibility aligns with good architectural practice
- Enables future migration to different AI providers without major refactoring

**Implementation Approach**:
- Abstract base class `AIAnalyzer` defining interface: `analyze_feedback(text: str, target_lang: str) -> AnalysisResult`
- Concrete implementation `ClaudeAnalyzer` using Anthropic API
- Configuration-driven provider selection
- API key management via environment variables

**Alternatives Considered**:
- **Hard-coded Claude API integration**: Simpler initially but violates user requirement for provider flexibility
- **LangChain framework**: Adds significant dependency weight for simple translation/categorization task
- **Multiple provider implementations from start**: Premature complexity - implement Claude first, abstract as needed

**Claude API Specifics**:
- Use `anthropic` Python SDK
- Model: `claude-3-haiku-20240307` for cost-effective analysis (fast, sufficient for categorization/translation)
- Prompt design: Single API call with structured output for category, summary, translation
- Error handling: Retry logic for transient failures, graceful degradation for persistent errors

**Research References**:
- Anthropic API Documentation: https://docs.anthropic.com/
- Python SDK: https://github.com/anthropics/anthropic-sdk-python

---

## 2. File Upload - Malware Scanning Approach

### Decision: ClamAV integration via clamd for virus scanning

**Rationale**:
- FR-060 requires malware scanning before storage
- ClamAV is open-source, widely used, actively maintained
- `clamd` provides Python bindings for integration
- Suitable for on-premise deployment matching file-based storage philosophy

**Implementation Approach**:
- Install ClamAV daemon (`clamd`) as system service
- Use `clamd` Python library for scanning uploaded files
- Scan files synchronously during upload before writing to disk
- Reject files that fail virus scan with clear error message
- Log scanning failures for security monitoring

**Configuration**:
- Maximum file size: 10MB per file (FR-006)
- Allowed extensions: `.pdf`, `.docx`, `.txt`, `.jpg`, `.png`, `.gif`, `.webp`
- MIME type validation in addition to extension checking
- Temporary upload storage cleaned after scan (pass or fail)

**Alternatives Considered**:
- **Cloud-based scanning (VirusTotal API)**: Violates anonymity requirement (uploads data externally), adds latency
- **No scanning**: Violates FR-060 security requirement
- **Manual review**: Not scalable, delays feedback processing
- **Python-based scanning (yara-python)**: More complex to configure, less comprehensive than ClamAV

**Dependencies**:
- `clamd` Python library
- ClamAV daemon installed on server

---

## 3. File Upload - Storage Location Strategy

### Decision: Local filesystem storage in `data/products/{product-id}/feedback/{feedback-id}/attachments/`

**Rationale**:
- Aligns with file-based storage architecture (no database)
- User input specifies "folders foreach user input" and "files in a folder"
- Simple to implement, backup, and inspect
- No additional service dependencies
- Sufficient for MVP scale (100 products × 10k items × 3 files × 10MB = ~30TB worst case)

**Directory Structure**:
```
data/
└── products/
    └── {product-id}/          # e.g., "001-acme-app"
        ├── config.yaml        # Product metadata (name, target language, owners)
        └── feedback/
            └── {feedback-id}/ # UUID v4, e.g., "a3f2c1d5-..."
                ├── metadata.yaml       # Feedback metadata (timestamp, status, category, etc.)
                ├── content.txt         # Original feedback text
                ├── analysis.md         # AI-generated analysis report
                └── attachments/
                    ├── original_filename_1.pdf
                    ├── original_filename_2.png
                    └── original_filename_3.jpg
```

**File Naming**:
- Preserve original filenames to maintain user context
- Sanitize filenames to prevent directory traversal (strip `../`, absolute paths, etc.)
- Handle duplicate filenames by appending counter if needed

**Alternatives Considered**:
- **Cloud storage (S3/GCS)**: Adds external dependency, cost, complexity; overkill for MVP
- **Flat directory per product**: Poor scalability, difficult to organize metadata
- **Database with BLOB storage**: Contradicts file-based storage decision, adds DB complexity
- **Content-addressed storage (hash-based filenames)**: Loses original filename context, complicates presentation

**Backup Strategy** (out of scope for MVP but noted):
- Simple filesystem backup via rsync/tar sufficient
- Can upgrade to cloud sync if needed later

---

## 4. Authentication - Session Management Approach

### Decision: Flask-Login with server-side sessions for product owners/admins

**Rationale**:
- Flask-Login is standard, well-tested session management for Flask
- Server-side sessions prevent token tampering
- Simple username/password authentication sufficient for MVP
- FR-056, FR-063 require authentication and secure password storage

**Implementation Approach**:
- Use `Flask-Login` extension for session management
- Store user credentials in simple YAML file (products/users.yaml) for MVP consistency with file-based approach
- Hash passwords with `bcrypt` (FR-063)
- Session cookies: `HttpOnly`, `Secure` (HTTPS only), `SameSite=Lax`
- Session timeout: 24 hours of inactivity

**User Model**:
```yaml
users:
  - id: "admin-001"
    email: "admin@example.com"
    password_hash: "$2b$12$..."
    role: "admin"
    assigned_products: []  # Empty = all products access

  - id: "owner-001"
    email: "owner@example.com"
    password_hash: "$2b$12$..."
    role: "product_owner"
    assigned_products: ["001-acme-app", "002-beta-service"]
```

**Access Control**:
- Admins: Full access to all products, can manage products/owners
- Product Owners: Read-only access to assigned products only (FR-033)
- Anonymous users: Submission form access only (no authentication)

**Alternatives Considered**:
- **JWT tokens**: More complex, unnecessary for server-rendered HTML application
- **OAuth/SAML**: Over-engineered for MVP, adds external identity provider dependency
- **Database-backed sessions**: Contradicts file-based architecture
- **No authentication**: Violates FR-056 requirement

**Dependencies**:
- `Flask-Login` extension
- `bcrypt` for password hashing

---

## 5. Rate Limiting - Implementation Strategy

### Decision: Flask-Limiter with IP-based rate limiting for submission endpoint

**Rationale**:
- FR-061 requires rate limiting (suggested: 10 submissions/hour/IP)
- Flask-Limiter is standard, well-maintained Flask extension
- IP-based limiting suitable for anonymous submissions
- In-memory storage sufficient for MVP (single server deployment)

**Implementation Approach**:
- Use `Flask-Limiter` extension
- Apply rate limit decorator to submission route: `@limiter.limit("10 per hour")`
- Storage backend: In-memory (default) for MVP
- Return HTTP 429 Too Many Requests with clear error message
- Exempt authenticated admin users from rate limits (for testing)

**Rate Limit Configuration**:
- Anonymous submission: 10 requests per hour per IP address
- Dashboard/admin routes: No rate limiting (authenticated users only)
- Rate limit headers included in response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

**Considerations**:
- IP-based limiting can be circumvented via VPN/proxy but sufficient deterrent for casual abuse
- Behind proxy/load balancer: Configure Flask-Limiter to read `X-Forwarded-For` header
- Note: FR-055 requires no fingerprinting for identification - rate limiting is for abuse prevention only, not user tracking

**Alternatives Considered**:
- **CAPTCHA (hCaptcha/reCAPTCHA)**: Adds friction to user experience, contradicts "lower barriers" goal
- **Redis-backed rate limiting**: Unnecessary complexity for single-server MVP
- **No rate limiting**: Violates FR-061 requirement, leaves system vulnerable to abuse
- **Token bucket per session**: Requires session tracking for anonymous users, violates anonymity

**Dependencies**:
- `Flask-Limiter` extension

---

## 6. Flask Best Practices for Simple HTML Applications

### Decision: Server-side rendering with Jinja2 templates, no JavaScript

**Rationale**:
- User explicitly specifies "plain html using flask" and "does not use any css frameworks or javascript libraries"
- Server-side rendering eliminates frontend build complexity
- Jinja2 included with Flask, no additional dependencies
- Forms use standard HTTP POST/GET, progressive enhancement approach

**Template Approach**:
- Minimal inline CSS for basic layout (no framework)
- Semantic HTML5 for accessibility
- Server-side form validation with error display
- Standard browser form controls (no custom widgets)

**Form Handling**:
- POST requests for submissions
- Server-side validation with error messages
- Flash messages for user feedback
- Redirect-after-POST pattern to prevent duplicate submissions

**No JavaScript Requirement** (Edge Case from spec.md line 105):
- "What happens when a user's browser doesn't support JavaScript"
- Answer: Application works fully without JavaScript (no JS used)
- File uploads work via standard HTML `<input type="file" multiple>`

**Best Practices Applied**:
- Flask app factory pattern for testability
- Blueprint organization for routes
- Environment-based configuration
- CSRF protection via Flask-WTF (even for simple forms)

**Dependencies**:
- Flask (includes Jinja2)
- Flask-WTF for CSRF protection

---

## 7. Python Dependency Management

### Decision: requirements.txt with pinned versions for reproducibility

**Rationale**:
- Simplest dependency management for Flask application
- No need for Poetry/Pipenv complexity in MVP
- Pin exact versions for reproducibility
- Virtual environment assumed for isolation

**Core Dependencies** (estimated):
```
Flask==3.0.0
Flask-Login==0.6.3
Flask-Limiter==3.5.0
Flask-WTF==1.2.1
anthropic==0.8.0
clamd==1.0.2
bcrypt==4.1.2
PyYAML==6.0.1
pytest==7.4.3
pytest-flask==1.3.0
```

**Development Dependencies**:
- pytest, pytest-flask for testing
- black for code formatting
- flake8 for linting

---

## Technology Stack Summary

| Component | Technology | Rationale |
|-----------|-----------|-----------|
| **Web Framework** | Flask 3.0+ | Lightweight, simple, widely supported |
| **Template Engine** | Jinja2 (built-in) | Server-side rendering, no JS needed |
| **AI Provider** | Claude API (Anthropic) | User-specified, abstracted for future flexibility |
| **Authentication** | Flask-Login + bcrypt | Standard session management, secure passwords |
| **Rate Limiting** | Flask-Limiter | Prevent abuse, simple IP-based approach |
| **Malware Scanning** | ClamAV + clamd | Open-source, reliable, on-premise |
| **Storage** | Filesystem (YAML + Markdown) | Matches user requirements, simple, no DB |
| **Testing** | pytest + pytest-flask | Industry standard, good Flask integration |
| **Python Version** | 3.11+ | Modern, stable, good performance |
| **Deployment** | Gunicorn (WSGI) | Production-ready Flask server |

---

## Non-Functional Requirements Research

### Performance Considerations

**Concurrent Submissions** (SC-012):
- Target: 100 concurrent submissions without errors
- Flask + Gunicorn with 4-8 worker processes should handle this
- File I/O is bottleneck: consider async I/O if performance issues arise
- AI analysis happens asynchronously (background task) to not block submission response

**Dashboard Performance** (SC-008):
- Target: Load 1000 items in <3 seconds
- File-based approach: Index product feedback directories, cache counts
- Implement pagination (50 items per page)
- Use lazy loading for file attachments (links, not embedded content)

**AI Analysis Time** (SC-007):
- Target: <30 seconds for 95% of submissions
- Claude Haiku model typically responds in 2-5 seconds for translation/categorization
- Timeout: 45 seconds before marking as failed
- Queue-based processing if needed (Python `queue` module or simple file-based queue)

### Security Considerations

**Anonymity Enforcement** (FR-055, SC-010):
- Do NOT log IP addresses in feedback metadata
- Rate limiting uses IP for abuse prevention only, not stored with feedback
- No session cookies for anonymous submission
- No analytics/tracking scripts

**File Upload Security**:
- Validate MIME types server-side (don't trust client)
- ClamAV scanning before storage
- Sanitize filenames to prevent directory traversal
- Store outside web root, serve via Flask route with access control

**HTTPS Requirement** (FR-064):
- Deployment guide must specify reverse proxy (nginx) with TLS
- Redirect HTTP to HTTPS
- HSTS headers recommended

---

## Open Questions for Implementation Phase

1. **Asynchronous AI Analysis**: Should analysis happen synchronously (user waits) or asynchronously (background job)?
   - **Recommendation**: Asynchronous - return success immediately, process in background
   - Implement simple file-based queue or use Python `threading` for MVP

2. **Admin Bootstrap**: How is the first admin user created?
   - **Recommendation**: CLI command or config file initialization script

3. **Email Notifications**: Out of scope (line 255) but commonly requested
   - **Recommendation**: Document as future enhancement, design hooks for extensibility

4. **Logging Strategy**: Structured logs for operational monitoring?
   - **Recommendation**: Python `logging` module, JSON format, separate file per environment

---

## Research Validation

All NEEDS CLARIFICATION items from Technical Context have been resolved:

| Item | Resolution | Document Section |
|------|------------|------------------|
| AI Integration | Pluggable interface, Claude as default | §1 |
| File Upload - Malware Scanning | ClamAV + clamd | §2 |
| File Upload - Storage Location | Filesystem: `data/products/.../feedback/.../attachments/` | §3 |
| Authentication | Flask-Login + server-side sessions + bcrypt | §4 |
| Rate Limiting | Flask-Limiter, 10/hour/IP | §5 |

**Next Phase**: Proceed to Phase 1 (data-model.md, contracts, quickstart.md)