Cottage Chooser – Technical Support

System Requirements

• Python 3.9–3.12
• pip and venv
• SQLite (bundled with Python)
• Windows, Linux, or macOS

Dependencies

flask>=2.2,<3
bleach>=6.1
requests>=2.31
# openai removed (manual summaries only)

Configuration (Environment Variables)

• CC_SECRET: Flask secret key. Defaults to "dev-secret-key". Set a strong value in production.
• CC_ALLOW_ADMIN_OVERRIDE: Enable admin override for deletes/edits (true/false/1/0/yes/no).
• CC_ADMIN_USERS: Comma-separated admin usernames (used with override).
• CC_ADMINS: Comma-separated admin usernames (used for vote/rating admin controls).

Note: The app unifies admin checks using both CC_ADMIN_USERS and CC_ADMINS. Either can grant admin rights. Usernames are case-insensitive and whitespace-trimmed.

Example (PowerShell): $env:CC_ADMINS = "alice,bob"

Local Setup (Windows, PowerShell)

cd C:\Users\Peter\Downloads\CottageChooser_Full
py -3 -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python app.py

If venv activation is blocked, run once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

The app will be available at http://localhost:5000

Database

• SQLite file: data.db (auto-created in the app folder).
• Initialize using /init route (loads schema.sql).
• Key tables:
  • cottages: name, location, price, beds, dogs_allowed, image, url, description, hottub, secure_garden, ev_charging, parking, log_burner, high_chair, cot, votes, submitted_by, ai_review_summary.
  • votes: id, cottage_id, user_name, voted_at (one active vote per user; denormalized count in cottages.votes).
  • comments: id, cottage_id, author, text, created_at (user reviews/comments on cottages).
  • ratings: id, cottage_id, user_name, rating (0-10), rated_at. UNIQUE constraint on (cottage_id, user_name) – one rating per user per cottage.
• Foreign Keys: All child tables (votes, comments, ratings) use ON DELETE CASCADE to auto-cleanup when cottages are deleted.

Application Features

• Join/Login: Group code authentication (default: "saywards").
• Cottage Management: Add, edit (own), delete (own or admin), list, compare, and view details.
• Voting System:
  • One vote per user (single choice)
  • Vote button on list page cards
  • Delete from Results page to change vote
  • Public voter lists on details pages
• Rating System:
  • Users rate cottages 0-10 (multiple cottages allowed)
  • Click rating buttons on cottage cards to submit/update
  • Delete ratings individually via "Clear my rating" or ratings detail page
  • View aggregate stats: count, average, total score
  • Regular users see only their own ratings + aggregates
  • Admins see all individual ratings on the ratings detail page
• Reviews & Comments:
  • Dedicated reviews page per cottage (/reviews/<id>)
  • Add, edit (own), delete (own or admin) comments
  • Reviews page shows cottage summary, rating stats, and all comments
  • Comments also appear on main details page
• Results: Ranked list by votes with rating statistics displayed.
• Compare: Side-by-side table with features, votes, and rating stats.
• Admin Controls:
  • Manage votes (view/delete any vote)
  • View all individual ratings per cottage
  • Delete any comment (with override enabled)
  • Delete any cottage (with override enabled)
• Presentation Mode: Slideshow viewer for PNG/JPG in static/slides/.
• Help Mode: Floating toggle; tooltips appear below elements.
• HTML Sanitization: Descriptions cleaned with Bleach (allowed tags: p, br, strong, em, u, ol, ul, li, h1-h4, blockquote).

Security Notes

• Set a strong CC_SECRET in production to protect sessions.
• Descriptions and comments are sanitized with Bleach to prevent XSS.
• Change the group code from "saywards" if privacy is required.
• Use HTTPS in production; ensure secure cookie flags.
• Rating system enforces one rating per user per cottage via database UNIQUE constraint.
• Comment editing restricted to original author or admin.
• Admin checks use normalized (case-insensitive, trimmed) usernames.

Deployment (Linux + Apache mod_wsgi)

1. Create a venv in the project directory and install requirements.
2. Create a WSGI entry file (e.g., cottage.wsgi) pointing to app.py.
3. Configure Apache VirtualHost to use mod_wsgi and point to the WSGI file.
4. Set environment variables (CC_SECRET, CC_ADMINS, CC_ALLOW_ADMIN_OVERRIDE, CC_ADMIN_USERS) in Apache config or .env file.
5. Ensure Apache user (e.g., www-data) can read the project directory and venv, and write to data.db and parent directory.
6. Set permissions:

   sudo chown -R www-data:www-data /path/to/app
   sudo chmod 664 /path/to/app/data.db
   sudo chmod 775 /path/to/app

7. Restart Apache: sudo systemctl restart apache2

Operations

• Backup: Stop the app, copy data.db and static/, templates/.
• Restore: Replace data.db, restart the app.
• Slides: Add images to static/slides/; optional static/presentation.pptx.
• Database Migration: If schema changes, either:
  • Visit /init (drops and recreates all tables – data loss!)
  • Manually run ALTER TABLE commands in SQLite shell
  • Use a migration tool like Alembic (not currently integrated)

Troubleshooting

Key Endpoints

Green highlight = reviews feature. Yellow highlight = rating system endpoints.

Rating & Review API Reference