Installation - Reflect AI

System Requirements

Reflect AI is a Flask-based web application that runs on your local machine. Before installing, ensure your system meets these requirements:

Python

Version 3.9 or higher
Check: python3 --version

pip

Python package manager
Usually included with Python

Disk Space

~500 MB
For Python packages and NLTK data

Browser

Modern web browser
Chrome, Firefox, Safari, or Edge

Installation Steps

Navigate to Project Directory

Open a terminal and change to the Reflect AI directory:

cd "PANW Hackathon Code"

Verify you’re in the right place:

ls -la

You should see:

app.py (Flask backend)
requirements.txt (dependencies)
index.html (frontend)
static/ directory (CSS, JS, assets)

Install Python Dependencies

Install all required packages using pip:

pip install -r requirements.txt

This installs:

flask
flask-cors
python-dotenv
groq
nltk

If you’re using a virtual environment (recommended), activate it before running pip install.

What Each Package Does

Package	Purpose	Version
`flask`	Web framework for the backend API	Latest
`flask-cors`	Enables cross-origin requests	Latest
`python-dotenv`	Loads environment variables from `.env`	Latest
`groq`	Groq API client for AI features	Latest
`nltk`	Natural Language Toolkit for sentiment analysis	Latest

Download NLTK VADER Lexicon

Reflect AI uses NLTK’s VADER (Valence Aware Dictionary and sEntiment Reasoner) for automatic mood detection. Download the required data:

python3 -c "import nltk; nltk.download('vader_lexicon')"

You’ll see output like:

[nltk_data] Downloading package vader_lexicon to
[nltk_data]     /Users/your-username/nltk_data...
[nltk_data] Package vader_lexicon is already up-to-date!

The app checks for VADER data on startup and will auto-download if missing, but manual installation is faster.

How VADER Works

From app.py:32-40:

# Download NLTK data (only once)
try:
    nltk.data.find('sentiment/vader_lexicon.zip')
except LookupError:
    logger.info("Downloading NLTK VADER lexicon...")
    nltk.download('vader_lexicon', quiet=True)

# Initialize sentiment analyzer
sia = SentimentIntensityAnalyzer()

VADER analyzes text and returns a compound score from -1 (very negative) to +1 (very positive).

Set Up Groq API Key

Groq powers AI features like personalized greetings, insights, and summaries. While optional, it’s highly recommended for the full experience.

Get Your API Key

Visit console.groq.com
Sign up for a free account
Navigate to API Keys
Create a new API key
Copy the key (starts with gsk_...)

Create Environment File

Create a .env file in the project root:

echo 'GROQ_API_KEY="gsk_your_actual_api_key_here"' > .env

Or manually create .env with:

.env

GROQ_API_KEY="gsk_your_actual_api_key_here"

How the App Uses Groq

From app.py:52-57:

GROQ_API_KEY = os.getenv("GROQ_API_KEY")

if GROQ_API_KEY:
    logger.info("Groq API configured for AI features")
else:
    logger.warning("No GROQ_API_KEY found. Get one free at https://console.groq.com")

Never commit your .env file to version control! Add it to .gitignore to keep your API key private.

What Works Without Groq?

These features work without a Groq API key:

✅ Basic journaling
✅ Mood detection (VADER)
✅ Streak tracking
✅ Calendar view
✅ Export/import
✅ Theme detection

These require Groq:

❌ AI-powered personalized greetings
❌ Weekly/monthly AI summaries
❌ Writing polish suggestions
❌ Pattern insights generation

Verify Installation

Check that everything is installed correctly:

python3 -c "import flask, nltk, groq, dotenv; print('All dependencies installed!')"

If successful, you’ll see:

All dependencies installed!

Test VADER

python3 -c "from nltk.sentiment.vader import SentimentIntensityAnalyzer; sia = SentimentIntensityAnalyzer(); print(sia.polarity_scores('Today was amazing!'))"

Expected output:

{'neg': 0.0, 'neu': 0.423, 'pos': 0.577, 'compound': 0.6588}

Project Structure

After installation, your project should look like this:

PANW Hackathon Code/
├── app.py                    # Flask backend (1,947 lines)
├── index.html               # Main HTML shell
├── static/
│   ├── app.js              # Frontend logic (1,479 lines)
│   ├── styles.css          # Styling with theme support
│   └── [assets]            # Images, icons, etc.
├── journal_data.json        # Your entries (auto-created on first save)
├── requirements.txt         # Python dependencies
├── .env                    # Environment variables (you create this)
└── README.md               # Project documentation

Running the Application

Start the Flask development server:

python3 app.py

Expected Output

2026-03-05 10:30:15,123 - INFO - Starting Reflect AI server...
2026-03-05 10:30:15,124 - INFO - Privacy-first design: All data stays local
2026-03-05 10:30:15,125 - INFO - Groq API configured for AI features
 * Serving Flask app 'app'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit

The development server is perfect for personal use. Flask’s warning about production deployment can be ignored for local journaling.

Access the Application

Open your browser and navigate to:

http://127.0.0.1:5000

You should see the Reflect AI loading screen with a personalized greeting, followed by the main calendar interface.

Data Storage

Reflect AI creates a journal_data.json file in the project root on your first save. This file contains all your entries.

Data Format

From app.py:64-90:

def load_data() -> Dict[str, Any]:
    """Load journal data from file with error handling."""
    if not os.path.exists(DATA_FILE):
        return {"entries": {}, "metadata": {"created_at": datetime.now().isoformat()}}
    
    try:
        with open(DATA_FILE, "r", encoding="utf-8") as f:
            data = json.load(f)
        return data
    except json.JSONDecodeError as e:
        logger.error(f"JSON decode error: {e}")
        return {"entries": {}, "metadata": {}}

Example Entry

journal_data.json

{
  "entries": {
    "2026-03-05": {
      "text": "Today was productive. Finished the project documentation and went for a run.",
      "photos": [],
      "tags": ["work", "health"],
      "sentiment": {
        "compound": 0.765,
        "mood": "positive",
        "scores": {
          "positive": 0.387,
          "negative": 0.0,
          "neutral": 0.613
        }
      },
      "themes": ["work", "health"],
      "word_count": 13,
      "updatedAt": "2026-03-05T14:23:45.123456"
    }
  },
  "metadata": {
    "created_at": "2026-03-05T14:23:45.123456"
  }
}

Backup Regularly: Use the Export button in the app to download a backup of journal_data.json. Store it somewhere safe!

Environment Variables

Reflect AI uses python-dotenv to load configuration from a .env file.

Supported Variables

Variable	Required	Default	Description
`GROQ_API_KEY`	No	`None`	Groq API key for AI features

Loading Process

From app.py:22-23:

from dotenv import load_dotenv
load_dotenv()

The app loads .env automatically on startup. Any changes require a server restart.

Troubleshooting

Common Issues

ModuleNotFoundError: No module named 'flask'

Problem: Python dependencies not installed.Solution:

pip install -r requirements.txt

If using a virtual environment, make sure it’s activated first.

[Errno 48] Address already in use

Problem: Port 5000 is already in use by another process.Solution:

# Find and kill the process using port 5000
lsof -ti:5000 | xargs kill -9

# Or run on a different port
python3 app.py --port 5001

LookupError: Resource vader_lexicon not found

Problem: NLTK VADER lexicon not downloaded.Solution:

python3 -c "import nltk; nltk.download('vader_lexicon')"

The app will auto-download on first run, but manual installation is faster.

Permission denied: 'journal_data.json'

Problem: File permissions prevent writing.Solution:

chmod 644 journal_data.json

Or delete the file and let the app recreate it:

rm journal_data.json

Groq API key not working

Problem: API key not loaded or invalid.Solution:

Verify .env file exists in project root
Check the key format: GROQ_API_KEY="gsk_..."
Restart the Flask server
Check server logs for “Groq API configured” message

Test the key directly:

python3 -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('GROQ_API_KEY'))"

Dark theme not persisting

Problem: Browser localStorage issue.Solution: Clear browser storage:

Open Developer Tools (F12)
Go to Application → Local Storage
Delete the theme key
Refresh the page

Getting Help

If you encounter issues not covered here:

Check the Flask server logs in your terminal
Open browser Developer Tools (F12) and check the Console for errors
Verify all files are in place: ls -la
Ensure Python version is 3.9+: python3 --version

Advanced Configuration

Using a Virtual Environment

Recommended for keeping dependencies isolated:

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Run the app
python3 app.py

Custom Port

The app defaults to port 5000. To use a different port, modify app.py:

app.py

if __name__ == "__main__":
    app.run(debug=False, host="127.0.0.1", port=5001)  # Change port here

Production Deployment

For Local Use Only: Reflect AI is designed for single-user, local operation. It lacks authentication and should not be exposed to the internet without additional security measures.

If you want to deploy on a local network:

Use a production WSGI server like Gunicorn:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

Consider adding authentication middleware
Use HTTPS with a reverse proxy like Nginx

Next Steps

Quickstart Guide

Write your first journal entry in under 5 minutes

Core Features

Learn about calendar views, prompts, and tags

AI Features

Explore AI-powered insights and summaries

API Reference

Complete API documentation for developers

Installation complete! You’re ready to start your journaling journey. 🎉

Get Started

Core Features

Guides

Privacy & Security

​System Requirements

Python

pip

Disk Space

Browser

​Installation Steps

​What Each Package Does

​How VADER Works

​Get Your API Key

​Create Environment File

​How the App Uses Groq

​What Works Without Groq?

​Test VADER

​Project Structure

​Running the Application

​Expected Output

​Access the Application

​Data Storage

​Data Format

​Example Entry

​Environment Variables

​Supported Variables

​Loading Process

​Troubleshooting

​Common Issues

​Getting Help

​Advanced Configuration

​Using a Virtual Environment

​Custom Port

​Production Deployment

​Next Steps

Quickstart Guide

Core Features

AI Features

API Reference

Build docs developers (and LLMs) love

System Requirements

Installation Steps

What Each Package Does

How VADER Works

Get Your API Key

Create Environment File

How the App Uses Groq

What Works Without Groq?

Test VADER

Project Structure

Running the Application

Expected Output

Access the Application

Data Storage

Data Format

Example Entry

Environment Variables

Supported Variables

Loading Process

Troubleshooting

Common Issues

Getting Help

Advanced Configuration

Using a Virtual Environment

Custom Port

Production Deployment

Next Steps