add readme

README.md

@@ -0,0 +1,81 @@
+# Couple Questions
+
+A small Python web application that provides randomly selected conversation questions for couples.
+
+The idea is inspired by physical conversation card games for couples where you draw a few cards and use the questions to start meaningful conversations. The goal is to help partners reflect, communicate intentionally, and get to know each other better.
+
+It is build to be run within a home network, no authentication whatsoever is implemented.
+
+Examples of such questions:
+
+- *When do you feel safe and supported by another person?*
+- *Which shared moment are you most proud of?*
+- *What do you need when you feel emotionally overwhelmed?*
+
+The application loads questions from YAML files, groups them by category, and randomly selects questions for the user.
+
+
+> [!NOTE]
+> This tool is intended only for use in a home network or other trusted environments. The container uses the built-in Flask development web server, which is not designed for direct exposure to the internet (or production workloads in general). Running this application publicly without proper hardening and a production-ready web server may expose security risks.
+
+## Features
+
+* Randomly selects conversation questions
+* Questions grouped by categories
+* Supports multiple YAML files for sorting questions
+* Weighted random selection:
+  * Questions that were asked recently are less likely to appear
+  * Weight increases with the number of days since last asked
+* Very simple interface, mobile friendly
+* Configurable via environment variables
+
+
+# Question Files
+
+The application expects question files as YAML files mounted under `/app/questions`.
+
+A sample file:
+
+```yaml
+Reflection:
+  - "When do you feel most supported by me?"
+  - "What helps you calm down when you feel overwhelmed?"
+  - "What personal growth are you most proud of?"
+
+Memories:
+  - "Which shared moment are you most proud of?"
+  - "What is one of your favorite memories of us together?"
+  - "What small moment with me made you unexpectedly happy?"
+
+Future:
+  - "What experience would you like us to share in the next few years?"
+  - "Where do you imagine us living in ten years?"
+```
+
+## Question Selection Logic
+
+The app keeps track of when each question was last asked.
+For every question:
+* A timestamp of the last access is stored.
+* The number of days since the last time it was asked is calculated. To avoid extreme weighting, this number of days is capped.
+
+This value is used as a weight for the random selection and reduces the probability of the same questions appearing repeatetly.
+
+# Deployment and configuration
+
+The app can be deployed with (docker) compose:
+
+```yaml
+services:
+  couplequestions:
+    image: registry.home.local/git-secretmine-cache/secretminede/couplequestions:latest
+    restart: always
+    environment:
+      NUM_QUESTIONS: 5 # Default number of questions preselected in the web UI
+      QUESTION_LAST_ACCESSED_DAYS_MAX: 30 # Maximum number of days used for weighting questions
+    volumes:
+      - ./questions:/app/questions # question files
+      - ./data:/app/data # simple json with the recently shown questions
+    ports:
+      - 5000:5000
+```