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

Implementation Plan: Anonymous Feedback Platform (Reklamator)

Branch: 001-build-an-application | Date: 2025-10-15 | Spec: spec.md Input: Feature specification from /specs/001-build-an-application/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

Build a minimal web application using Flask that enables anonymous feedback submission with AI-powered analysis and translation. The system uses a file-based storage approach with folders for each submission, YAML metadata files, and markdown-formatted AI analysis reports. Product owners access analyzed feedback through an authenticated web dashboard. Design prioritizes simplicity and functionality over aesthetics - plain HTML without CSS frameworks or JavaScript libraries.

POC Scope Update (2025-10-17): User Story 4 (Product/Service Registration and Management) has been deferred for the proof-of-concept. Products and users will be managed manually via YAML configuration files (data/products/{id}/config.yaml and data/users.yaml). This decision removes admin UI complexity while maintaining full functionality for POC validation. User Stories 1-3 (Anonymous Submission, AI Analysis, Dashboard) remain in scope and are IMPLEMENTED.

Technical Context

Language/Version: Python 3.11+ Primary Dependencies: Flask (web framework), no CSS frameworks, no JavaScript libraries Storage: File-based - folders per feedback item with YAML metadata and markdown reports Testing: pytest (contract and integration tests prioritized per constitution) Target Platform: Linux server (web application) Project Type: web (backend + frontend, but minimal frontend without frameworks) AI Integration: NEEDS CLARIFICATION - Claude API or pluggable AI provider interface Performance Goals: Handle 100 concurrent submissions, <3s dashboard load for 1000 items Constraints: <30s AI analysis time for 95% of submissions, complete anonymity (no IP/session tracking) Scale/Scope: MVP supports 100 products, 10,000 feedback items per product, 50+ languages File Upload: NEEDS CLARIFICATION - malware scanning approach, storage location strategy Authentication: NEEDS CLARIFICATION - session management approach for product owners Rate Limiting: NEEDS CLARIFICATION - implementation strategy for submission abuse prevention

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

✅ I. Specification-First Development

Status: PASS Complete specification exists at specs/001-build-an-application/spec.md with prioritized user stories (P1-P4), 64 functional requirements with unique IDs (FR-001 to FR-064), measurable success criteria (SC-001 to SC-014), and comprehensive edge cases. All user stories are independently testable.

✅ II. Test-First Discipline

Status: PASS (Will be enforced during implementation) Plan includes pytest as testing framework. Implementation phase will follow mandatory workflow: write tests → verify failures → implement code → refactor. Contract and integration tests prioritized per constitution.

✅ III. Independent User Stories

Status: PASS Four user stories explicitly prioritized (P1: Anonymous Submission, P2: AI Analysis, P3: Dashboard, P4: Product Management). Each story is independently deliverable and testable. P1 can function standalone, P2 depends only on P1, P3 on P1+P2, P4 adds multi-product support.

✅ IV. Simplicity & Justification

Status: PASS Design explicitly minimizes complexity: plain HTML without CSS frameworks, no JavaScript libraries, file-based storage (no database), Flask for web framework (minimal dependencies). User input emphasizes "designed as simple as possible" and "functionality over design."

Potential Complexity Point: File-based storage vs. database

• Decision: File-based storage with folder-per-feedback structure
• Rationale: Simpler deployment, no database setup/maintenance, natural fit for storing files+metadata together, sufficient for MVP scale (100 products × 10k items)
• Alternative Rejected: PostgreSQL/SQLite - adds operational complexity, requires schema migrations, doesn't simplify file attachment handling

✅ V. Documentation as Code

Status: PASS Specification-driven workflow with all documentation in version control under /specs/001-build-an-application/. This plan will generate: research.md, data-model.md, contracts/, quickstart.md per constitution requirements.

Gate Result: ✅ PASS - Proceed to Phase 0 Research

No constitutional violations detected. Complexity Tracking table remains empty.

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

reklamator/
├── app/
│   ├── __init__.py          # Flask app factory
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── submission.py    # Anonymous feedback submission endpoints
│   │   ├── dashboard.py     # Product owner dashboard endpoints
│   │   └── admin.py         # Product/owner management endpoints
│   ├── services/
│   │   ├── __init__.py
│   │   ├── feedback_storage.py    # File-based storage operations
│   │   ├── ai_analyzer.py         # AI analysis/translation interface
│   │   └── auth.py                # Session management
│   ├── models/
│   │   ├── __init__.py
│   │   ├── feedback.py      # Feedback domain model
│   │   ├── product.py       # Product domain model
│   │   └── user.py          # Product owner/admin model
│   ├── templates/           # Plain HTML templates (Jinja2)
│   │   ├── submission_form.html
│   │   ├── dashboard.html
│   │   ├── feedback_detail.html
│   │   └── admin_products.html
│   └── utils/
│       ├── __init__.py
│       ├── file_validator.py     # File upload validation
│       └── rate_limiter.py       # Submission rate limiting
│
├── data/                    # File-based storage root
│   └── products/
│       └── {product-id}/
│           └── feedback/
│               └── {feedback-id}/
│                   ├── metadata.yaml
│                   ├── analysis.md
│                   └── attachments/
│
├── tests/
│   ├── contract/            # API contract tests
│   │   ├── test_submission_api.py
│   │   ├── test_dashboard_api.py
│   │   └── test_admin_api.py
│   ├── integration/         # User journey tests
│   │   ├── test_feedback_submission_flow.py
│   │   ├── test_ai_analysis_flow.py
│   │   └── test_dashboard_access_flow.py
│   └── unit/                # Optional unit tests for complex logic
│       ├── test_feedback_storage.py
│       └── test_file_validator.py
│
├── config/
│   ├── development.py
│   ├── production.py
│   └── testing.py
│
├── requirements.txt
├── pytest.ini
└── run.py                   # Application entry point

Structure Decision: Selected web application structure (Option 2 variant) with backend-focused layout since frontend is minimal (plain HTML templates). Flask follows a single-project structure but organized by layers (routes/services/models). The data/ directory implements the file-based storage requirement with nested folders per product and feedback item. Templates directory contains plain HTML served by Flask without separate frontend build process.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

No violations detected. Table remains empty.

---

Post-Design Constitution Re-Check

Re-evaluated after Phase 1 design completion

✅ I. Specification-First Development

Status: PASS (unchanged) Design artifacts (research.md, data-model.md, contracts/, quickstart.md) generated from specification. No implementation code written yet.

✅ II. Test-First Discipline

Status: PASS (unchanged) API contracts define testable behaviors. Contract tests can be written before implementation. Quickstart guide includes test-first workflow examples.

✅ III. Independent User Stories

Status: PASS (unchanged) Data model and API contracts support independent implementation of P1→P2→P3→P4 stories. Each has clear endpoints and data structures.

✅ IV. Simplicity & Justification

Status: PASS (confirmed post-design)

• File-based storage design confirmed (YAML + Markdown)
• No database complexity introduced
• Minimal dependencies: Flask + 7 small extensions
• Plain HTML templates (no CSS frameworks, no JavaScript)
• Direct file I/O (no ORM or abstraction layers)
• Single-project structure (no microservices)

Design Review: All research decisions favor simplicity. No new complexity introduced during Phase 1.

✅ V. Documentation as Code

Status: PASS (enhanced) Generated artifacts:

• ✅ research.md (7 decision records)
• ✅ data-model.md (6 entities fully specified)
• ✅ contracts/ (3 web route contracts: submission, dashboard, admin)
• ✅ quickstart.md (developer onboarding guide)
• ✅ CLAUDE.md (agent context updated)

All documentation version-controlled, linked to spec.md.

Final Gate Result: ✅ PASS - Ready for Phase 2 (Task Generation)

No constitutional violations introduced during design phase. Proceed to /speckit.tasks command.