Skip to main content

​
Welcome to Reflect AI

Reflect AI is a privacy-first journaling web application that helps you maintain a consistent reflection habit. All your data stays local on your device—no cloud uploads, no tracking, just you and your thoughts. This guide will take you from zero to your first journal entry in minutes.

​
Prerequisites

Before you begin, make sure you have:

Python 3.9+

Check your version with python3 --version

pip

Python package manager (usually included with Python)

​
Quick Installation

1

Navigate to the project directory

cd "PANW Hackathon Code"
2

Install dependencies

pip install -r requirements.txt
This installs Flask, NLTK, Groq, and other required packages.
3

Download NLTK sentiment data

python3 -c "import nltk; nltk.download('vader_lexicon')"
This is a one-time setup. The VADER lexicon enables automatic mood detection in your journal entries.
4

Set up your Groq API key (optional)

Get a free API key from console.groq.com, then:
echo 'GROQ_API_KEY="your_api_key_here"' > .env
AI features work without this, but you’ll get enhanced insights, personalized greetings, and AI-powered summaries with a Groq API key.

​
Start the Application

Launch the Flask server: 
python3 app.py
You’ll see output like this: 
2026-01-31 21:41:42,357 - INFO - Starting Reflect AI server...
2026-01-31 21:41:42,357 - INFO - Privacy-first design: All data stays local
 * Running on http://127.0.0.1:5000
Open your browser and navigate to: 
http://127.0.0.1:5000

​
Write Your First Entry

1

Click 'Write Today'

The big blue button in the sidebar takes you straight to today’s entry.
2

Choose a writing style (optional)

Select from pre-built prompts:
  • Free - Blank canvas for stream-of-consciousness
  • Gratitude - Focus on what you’re thankful for
  • Reflection - Highlights and lessons from your day
  • Goals - Set intentions
  • Emotions - Process how you’re feeling
3

Write your thoughts

Start typing in the text area. The app automatically:
  • Tracks your word count in real-time
  • Saves your work (no auto-save, click Save when ready)
  • Analyzes sentiment when you save
4

Save your entry

Click the Save button. Within seconds, you’ll see:
  • Your mood emoji (😊, 🙂, 😐, 😔, etc.)
  • Encouraging feedback based on your mood
  • Updated streak counter
Your entry is stored locally in journal_data.json. No data ever leaves your device unless you explicitly export it.

​
What Happens Next?

After saving your first entry:

View on Calendar

Return to the month view to see your entry with its mood emoji on the calendar.

Build Your Streak

Write daily to build a streak. Hit 7 days for your first badge!

Explore Insights

After 3+ entries, visit the Insights tab for mood trends and pattern analysis.

Export Anytime

Click Export in the sidebar to download your complete journal as JSON.

​
Key Features to Try

​
Automatic Mood Detection

Every entry is analyzed with NLTK’s VADER sentiment analyzer: 
# From app.py:128-159
def analyze_sentiment(text: str) -> Dict[str, Any]:
    scores = sia.polarity_scores(text)
    compound = scores["compound"]
    
    # Determine mood label with nuanced thresholds
    if compound >= 0.5:
        mood = "very_positive"
    elif compound >= 0.2:
        mood = "positive"
    elif compound > -0.2:
        mood = "neutral"
    elif compound > -0.5:
        mood = "negative"
    else:
        mood = "very_negative"

​
Streak Tracking

Stay motivated with visual streak counters:
  • Current Streak: Consecutive days of journaling
  • Weekly Chain: See which days this week you’ve written
  • Badges: Unlock milestones at 7, 14, 30, 60, 100, and 365 days

​
Theme Detection

The app automatically identifies themes in your writing: 
# From app.py:319-344
theme_keywords = {
    "work": ["work", "job", "office", "meeting", "project"],
    "family": ["family", "mom", "dad", "parent", "sister"],
    "health": ["gym", "workout", "exercise", "run", "yoga"],
    "emotions": ["happy", "sad", "anxious", "excited"],
    # ...more themes
}

​
Next Steps

Installation Details

Learn about dependencies, NLTK setup, and environment configuration

Core Features

Explore calendar views, prompts, tags, and photos

AI Features

Discover AI-powered insights, summaries, and writing assistance

Analytics

Dive into mood trends, theme analysis, and interactive charts
Privacy First: Reflect AI stores all data locally in journal_data.json. No cloud sync means complete control, but also means you should back up regularly using the Export feature.

​
Troubleshooting

​
Port Already in Use

If port 5000 is busy: 
# Kill existing process
lsof -ti:5000 | xargs kill -9

# Or use a different port
python3 app.py --port 5001

​
Can’t Find NLTK Data

Re-download the VADER lexicon: 
python3 -c "import nltk; nltk.download('vader_lexicon')"

​
Module Not Found Errors

Reinstall dependencies: 
pip install -r requirements.txt --force-reinstall
Ready to reflect? Open the app and start your journaling journey today! 🌟

Build docs developers (and LLMs) love

Get started for freeTalk to us