Reflection Logo

About

Reflection is a powerful yet user-friendly web application designed to help you track and understand your daily well-being. Whether you're managing stress, monitoring mood patterns, or building habits, Reflection provides the tools you need to gain meaningful insights into your routine.

Built with modern technologies including Streamlit for the web interface, Plotly for beautiful data visualizations, and pandas for intelligent data analysis, Reflection offers a seamless experience for recording and exploring your mood data. All your entries are stored locally in a high-performance SQLite database, ensuring your personal data remains private and accessible.

Built With

• Python - Core programming language
• Streamlit - Web application framework
• Plotly - Data visualization library
• SQLite - Local database storage
• pandas - Data analysis toolkit

Version Control

This project uses Git for version control and is hosted on Codeberg.

Features

• 📊 Daily Mood Tracking: Record daily stress, joy, physical, and mental scores (0–10 scale).
• 🕸️ Weekly Activity Radar: Define activities with targets and visualize completion across the week.
• 📈 Data Visualization: Visualize daily entries in a monthly heatmap with Excel-like color scaling.
• 📅 Annual Overview: Explore an annual overview with mini-calendars and per-day averages.
• ⚡ High Performance: SQLite backend with optimized queries and indexing for fast data operations.
• 📤📥 Data Portability: Import legacy data from Excel/JSON, export reports, and manage local backups.

Screenshots

Project Layout

📁 reflection/
├── 📄 pyproject.toml # Project config and dependencies
├── 📄 Dockerfile # Docker image build
├── 📄 docker-compose.yml # Local deployment
├── 📄 README.md # Documentation
├── 📁 reflection_app/ # Application package
│ ├── 📄 main.py # Streamlit entry point
│ ├── 📄 config.py # App configuration
│ ├── 📁 data/ # Data models + SQLite store
│ ├── 📁 services/ # Aggregation logic
│ ├── 📁 ui/ # Streamlit UI + localization
│ └── 📁 tools/ # Utilities (seed scripts)
├── 📁 docs/ # Docs and screenshots
│ └── 📁 images/
└── 📁 tests/ # Test suite

Getting Started

Demo Data

To generate demo data for screenshots or testing, you can use the seeding script:

python -m reflection_app.tools.seed_demo --year 2025 --purge

This will purge and recreate local data under ~/.reflection (or the path set in REFLECTION_DATA_DIR). It only affects your local files, not the Docker volume unless you mapped it to the same directory.

Running with Docker (Recommended)

The easiest way to run Reflection is using Docker:

1. Using Docker Compose (recommended for data persistence):

   docker-compose up --build
   

2. Using Docker directly:

   docker build -t reflection .
   docker run -p 8501:8501 -v reflection_data:/app/data reflection
   

⚠️ Note on Permissions (Non-Root User)

Reflection now runs inside Docker using a non-root user for improved security. When using Docker volumes, this means the application directory /app/data must be writable by the container.

On first run, Docker creates the reflection_data volume automatically with the correct permissions. However, if you previously used Reflection before this update, your existing Docker volume may contain files owned by root, causing SQLite to raise:

sqlite3.OperationalError: attempt to write a readonly database

To fix this while keeping your data, update the ownership of the existing Docker volume:

docker run --rm -it \
 -v reflection_reflection_data:/app/data \
 --user 0 alpine sh -c 'chown -R 1000:1000 /app/data'

After this fix, restart the app:

docker-compose down
docker-compose up -d

This step is required only once when upgrading from a version that previously used root inside the container.

Running Locally (Development)

1. Create a virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate # or .venv\Scripts\activate on Windows
   pip install -e .[dev]
   

2. Launch the application in development mode:

   streamlit run reflection_app/main.py/mode
   

3. Open your browser to the URL shown in the terminal (usually http://localhost:8501)

Configuration

The application now uses a comprehensive configuration management system with support for:

• Data Storage: SQLite database at ~/.reflection/mood_entries.db by default
• Environment Variables: Override settings with:
  • REFLECTION_DATA_DIR=/path/to/data - Custom data directory
  • REFLECTION_BACKUP_COUNT=30 - Number of backups to keep
  • REFLECTION_UI_THEME=light|dark|auto - UI theme preference
  • REFLECTION_LOG_LEVEL=INFO - Logging level
  • REFLECTION_WINDOW_WIDTH=1100 - Window dimensions
  • REFLECTION_AUTO_SAVE=true - Auto-save behavior
• Configuration File: Settings saved to ~/.reflection/config.json
• Backup Management: Automatic backups stored in ~/.reflection/backups/

Backup & Restore

The SQLite database provides automatic data persistence. For manual backup/restore functionality:

• Database Location: Data is stored in /app/data/mood_entries.db within the Docker container
• Docker Volume: Use docker-compose.yml volume reflection_data for persistent storage
• Manual Backup: Copy the database file from the Docker volume when needed
• Future Enhancement: Export/import functionality will be added to the web interface

Development Notes

• Python 3.10+: The application targets modern Python versions.
• Testing: Comprehensive test suite with pytest covering:
  • Configuration management
  • Enhanced logging system
  • SQLite backend performance and reliability
  • Data models and validation
• Code Quality: Style enforced with black and ruff for consistent formatting.
• Logging: Enhanced logging system with:
  • Structured JSON logging for analysis
  • Performance tracking for optimization
  • Configurable log levels and outputs
  • Automatic log rotation (10MB files, 5 backups)
• Web Framework: Built with Streamlit for easy web deployment and Docker containerization

Roadmap

🚀 Near-Term Priorities (Next 3-6 Months)

1. 📤📥 Enhanced Data Export/Import System

• JSON/CSV export with date range selection
• Bulk import from spreadsheets and other mood trackers
• Data migration tools for seamless transitions
• Backup scheduling with automatic cloud sync options

2. 📊 Advanced Analytics & Insights Dashboard

• Trend analysis with moving averages and seasonal patterns
• Correlation detection between mood metrics and external factors
• Predictive insights using simple ML models for mood forecasting
• Custom reporting with charts and statistical summaries
• Mood pattern recognition (cycles, triggers, improvements)

3. 🎯 Customizable Metrics & Goals

• User-defined metrics beyond stress/joy/physique/mental
• Goal setting with progress tracking and notifications
• Weighted scoring for different metric importance
• Metric categories and tagging system
• Flexible scoring scales (not just 0-10)

4. 🔐 User Management & Privacy

• Multiple user accounts with data isolation
• Privacy controls for data sharing and anonymized analytics
• Data encryption for sensitive mood information
• Account backup/restore across devices
• Guest mode for trying the app without commitment

📋 Implementation Status

• ✅ Web app conversion - Complete
• ✅ Docker containerization - Complete
• ✅ Basic CRUD operations - Complete
• 🔄 Data export/import - In progress (basic functionality exists)
• 📅 Advanced analytics - Planned for Q4 2025
• 📅 Custom metrics - TBD
• 📅 User Management & Privacy - TBD

See the open issues for a complete list of proposed features and known issues.

Support

Reach out to the maintainer at one of the following places:

• Codeberg issues
• Contact options listed on this Codeberg profile

Project assistance

If you want to say thank you or/and support active development of Reflection:

• Add a Star to the project.
• Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make Reflection better!

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Authors & contributors

The original setup of this repository is by Medenor.

For a full list of all authors and contributors, see the contributors page.

Security

Reflection follows good practices of security, but 100% security cannot be assured. Reflection is provided "as is" without any warranty. Use at your own risk.

License

This project is licensed under the GNU AGPLv3 license.

Disclaimer – Vibe coding & AI assistance

This repository was developed using a vibe coding approach, with assistance from AI tools.

The code was written iteratively, with human review, testing, and decision-making at each step.
AI assistance was used to accelerate ideation, refactoring, and documentation, but responsibility for the design choices, validation, and final output remains entirely human.

Transparency matters: this project reflects a human–AI collaborative workflow.

Acknowledgements

• Repository files templates provided by dec0dOS/amazing-github-template
• Spider radar activity tracker inspired by Weekly-Radar from Baldev8910 on GitHub