README.md.backup

# 🧠 Soul Sense EQ Test

Soul Sense EQ Test is a desktop-based Emotional Intelligence (EQ) assessment application built using Python, Tkinter, and SQLite.
It provides a ✅ Tip: If you see `ModuleNotFoundError`, it usually means your virtual environment is **not active** or the package isn't installed inside it.

---

## 🌍 Multi-language Support

SoulSense now supports multiple languages with easy switching!

### Supported Languages

- **English** (default)
- **हिंदी (Hindi)**
- **Español (Spanish)**

### Quick Start

1. Launch the application
2. Select your language from the dropdown at the top of the main screen
3. All UI elements update instantly
4. Your preference is saved automatically

### For Contributors

Want to add your language? See our [I18N Guide](docs/I18N_GUIDE.md) for:

- Step-by-step instructions
- Translation template
- Testing guidelines

<div align="center">

# Frequently Asked Questions

Everything you need to know about the **Soul Sense Exam**.

</div>

<table>
<tr>
<td width="65%" valign="top">

### User FAQs

<details>
<summary><strong>Is this a medical or diagnostic test?</strong></summary>
<br>
No. This application is not a medical or psychological diagnostic tool. It is meant for self-reflection and educational purposes only.
</details>

<details>
<summary><strong>Are my responses stored?</strong></summary>
<br>
User responses may be stored securely to improve insights and future features. Personal data is handled responsibly and with user consent.
</details>

<details>
<summary><strong>Can I retake the exam?</strong></summary>
<br>
Yes, users can retake the exam to track changes in their emotional patterns over time.
</details>

<details>
<summary><strong>How are the results calculated?</strong></summary>
<br>
Results are generated based on predefined logic and, in future updates, may use data-driven or ML-based analysis.
</details>

<details>
<summary><strong>Can I edit my personal details later?</strong></summary>
<br>
Yes, users will be able to update their profile information as new features are added.
</details>

<details>
<summary><strong>Will this app give therapy or treatment advice?</strong></summary>
<br>
No. The app may provide general insights or suggestions, but it does not replace professional help.
</details>

<details>
<summary><strong>Is my data shared with others?</strong></summary>
<br>
No personal data is shared without consent. Any data used for analysis is anonymized.
</details>

<details>
<summary><strong>Who should I contact for support or feedback?</strong></summary>
<br>
You can raise an issue on the GitHub repository or contact the project maintainers through the community channels.
</details>

<br>
<hr>

## 🛠️ Developer Guide (Run Locally)

### 1. Prerequisites

- Python 3.13+ (recommended) or Python 3.8+
- [Git](https://git-scm.com/)

### 2. Installation

1.  **Clone the repository:**

    ```bash
    git clone https://github.com/Rohanrathod7/soul-sense-Exam.git
    cd soul-sense-Exam/SOUL_SENSE_EXAM
    ```

2.  **Set up a virtual environment (Recommended):**

    ```bash
    python -m venv .venv
    # Windows PowerShell
    .\.venv\Scripts\Activate.ps1
    # Windows Command Prompt
    .\.venv\Scripts\activate.bat
    # Mac/Linux
    source .venv/bin/activate
    ```

3.  **Install dependencies:**

    ```bash
    pip install -r requirements.txt
    ```

4.  **Initialize the database:**

    ```bash
    # Run database migrations
    alembic upgrade head

    # Seed the question bank
    python scripts/setup/seed_questions_v2.py
    ```

5.  **Configure Environment Variables:**

    The application now includes robust environment validation on startup.

    **For Development (Default):**

    ```bash
    # Copy the example environment file
    cp .env.example .env
    ```

    The `.env.example` file contains all required and optional variables with sensible defaults for development.

    **For Production/Staging:**

    Set the following required environment variables in your `.env` file:

    ```bash
    # Required for all environments
    APP_ENV=production  # or 'staging'
    DATABASE_URL=postgresql://user:password@host:port/database
    JWT_SECRET_KEY=your_super_secret_key_here

    # Additional required for staging/production
    DATABASE_HOST=your_database_host
    DATABASE_PORT=5432
    DATABASE_NAME=your_database_name
    DATABASE_USER=your_database_user
    DATABASE_PASSWORD=your_secure_password
    ```

    **Environment Validation:**

    The application will validate all environment variables on startup and fail fast if:
    - Required variables are missing
    - Variables have invalid types or values
    - Database URLs are malformed

    Check the startup logs for a validation summary and any errors or warnings.

### 3. Running the Application

**Easy Launch (Recommended):**

- **Windows PowerShell:**

  ```bash
  .\run.ps1
  ```

- **Windows Command Prompt:**
  ```bash
  run.bat
  ```

**Manual Launch:**

- **Desktop GUI (Main App):**

  ```bash
  # Make sure virtual environment is activated first
  .\.venv\Scripts\Activate.ps1   # Windows PowerShell
  python -m app.main
  ```

- **CLI Version (Terminal Mode):**
  ```bash
  python -m app.cli
  ```

### 4. Running Tests

Run the full test suite to verify your environment:

```bash
python -m pytest tests/
```

To run the startup integrity specific tests:

```bash
python -m pytest tests/test_startup_checks.py -v
```

### 5. Troubleshooting

<details>
<summary><strong>ModuleNotFoundError: No module named 'tkcalendar' or 'sqlalchemy'</strong></summary>
<br>

**Issue:** Dependencies are not installed in the virtual environment.

**Solution:**

```bash
# Activate your virtual environment first
.\.venv\Scripts\Activate.ps1   # Windows PowerShell

# Then install all dependencies
pip install -r requirements.txt
```

</details>

<details>
<summary><strong>Database error: no such table: question_bank</strong></summary>
<br>

**Issue:** Database is not initialized.

**Solution:**

```bash
# Run migrations to create all tables
alembic upgrade head

# Seed the questions
python scripts/setup/seed_questions_v2.py
```

</details>

<details>
<summary><strong>SQLAlchemy compatibility error with Python 3.13</strong></summary>
<br>

**Issue:** Old SQLAlchemy version incompatible with Python 3.13.

**Solution:** The requirements.txt already specifies SQLAlchemy 2.0.36+ which is compatible. Just reinstall:

```bash
pip install -r requirements.txt --upgrade
```

</details>

<details>
<summary><strong>Application starts but immediately closes</strong></summary>
<br>

**Issue:** Database not initialized or missing questions.

**Solution:** Follow step 4 in Installation to initialize the database and seed questions.

</details>

### 6. Git Workflow Commands

If you are contributing to the project, use these common Git commands:

```bash
git status                # Check which files have changed
git add .                 # Stage all changes for commit
git commit -m "feat: description"  # Commit your changes
git push origin main      # Push changes to your fork/branch
git fetch origin          # Get latest changes from remote
git pull origin main      # Update your local branch
```

<hr>
<h3>Contributor FAQs</h3>

<details>
<summary><strong>How do I run this project locally?</strong></summary>
See the <strong>Developer Guide</strong> section above for full setup instructions.
</details>
<br>
Clone the repo, set up a virtual environment (<code>python -m venv venv</code>), install dependencies with <code>pip install -r requirements.txt</code>, and run <code>python -m app.main</code> to launch the application.
</details>

<details>
<summary><strong>What is the Tech Stack?</strong></summary>
<br>
This project utilizes Python 3.11+, Tkinter for the GUI, SQLite for the database, and Pytest for testing.
</details>

<details>
<summary><strong>Found a bug?</strong></summary>
<br>
Please open an issue describing the bug, steps to reproduce it, and the expected behavior. Pull Requests with fixes are welcome!
</details>

</td>
<td width="35%" valign="top" align="center">

<br>
<img src="https://placehold.co/400x400/6c63ff/ffffff?text=SOUL%0ASENSE%0AEQ&font=montserrat" alt="Soul Sense Logo">

</td>
</tr>
</table>

---

## 🔐 Admin Interface

SoulSense includes a powerful admin interface for managing questions and categories.

### Features

- **GUI Admin Panel** - User-friendly graphical interface
- **CLI Tool** - Command-line interface for automation
- **Secure Access** - Password-protected admin accounts
- **CRUD Operations** - Create, Read, Update, Delete questions
- **Category Management** - Organize questions by category
- **Metadata Support** - Age range, difficulty, weight customization

### Quick Start

**Create Admin Account:**

```bash
python admin_cli.py create-admin --no-auth
```

**Launch GUI:**

```bash
python admin_interface.py
```

**CLI Commands:**

```bash
python admin_cli.py list                    # List all questions
python admin_cli.py add                     # Add new question
python admin_cli.py view --id 1             # View question
python admin_cli.py update --id 1           # Update question
python admin_cli.py delete --id 1           # Delete question
python admin_cli.py categories              # View statistics
```

### Documentation

See [ADMIN_GUIDE.md](docs/ADMIN_GUIDE.md) for comprehensive documentation.

---

## ▶️ How to Runeractive self-reflection test, persists results locally, and is designed with maintainability, testability, and extensibility in mind.

**🌍 Now available in multiple languages: English, Hindi (हिंदी), and Spanish (Español)!**

The application is grounded in established emotional intelligence theory (Salovey & Mayer, 1990; Goleman, 1995) and incorporates evidence-based approaches for self-report EI assessment (Petrides & Furnham, 2001). For comprehensive academic references, see [RESEARCH_REFERENCES.md](docs/references/RESEARCH_REFERENCES.md).

---

## ✨ Features

- **🌐 Multi-language Support (NEW!)**
  - English, Hindi, and Spanish translations
  - Easy language switching from the UI
  - Persistent language preferences
  - Simple framework for adding more languages
- **User Authentication System**
  - Secure user registration and login
  - Password hashing with bcrypt (12 rounds)
  - Session management with logout functionality
  - User-specific data tracking
- **Outlier Detection & Data Quality**
  - Statistical outlier detection using multiple methods (Z-score, IQR, MAD, Modified Z-score)
  - Ensemble outlier detection with consensus voting
  - Inconsistency pattern detection for users
  - Age-group and global analysis capabilities
  - Comprehensive data quality reporting
- Interactive Tkinter-based GUI
- SQLite-backed persistence for questions, responses, and scores
- Questions loaded once into the database, then read-only at runtime
- Automatic EQ score calculation with interpretation
- Stores:
  - Per-question responses
  - Final EQ score
  - Optional age and age group
  - User authentication data
- Backward-compatible database schema migrations
- Pytest-based test suite with isolated temporary databases
- **Enhanced User Profile (NEW!)**
  - **Medical Profile**: Track allergies, conditions, and emergency contacts
  - **Personal History**: Visual timeline of life events
  - **Strengths & Goals**: Track personal strengths, learning styles, and aspirations
  - **Avatar Customization**: Upload and crop profile pictures
- Daily emotional journal with AI sentiment analysis
- Emotional pattern tracking and insights
- **Emotional Patterns Capture (NEW!)** - Define your common emotional states for personalized AI responses
- View past journal entries and emotional journey
- **Startup Integrity Checks (NEW!)**
  - Validates database schema and required files at startup
  - Auto-recovery for missing directories or corrupted config
  - User-friendly diagnostic alerts
- **Database Backup & Restore (NEW!)**
  - Create timestamped local backups of your data
  - Restore from any previous backup with safety copy
  - Manage backups via Settings → Data Backup
- **Loading States for Long Operations (NEW!)**
  - Visual feedback during PDF export, AI analysis, and data export
  - Animated loading overlay prevents user confusion
  - Automatic cleanup on completion or error
- **Delete My Data (NEW!)**
  - Permanently delete all your personal data from the application
  - Two-step confirmation dialog for safety
  - Removes all user records, profiles, journals, settings, and local files
  - Accessible via Profile → Settings → Data Management
- **Settings Synchronization (NEW!)**
  - Sync user preferences and non-sensitive settings across clients
  - Key-value based API with version-based conflict detection
  - Integrated with user authentication for data isolation
  - Accessible via the REST API endpoints

---

## 📝 Journal Feature

The journal feature allows users to:

- Write daily emotional reflections
- Get AI-powered sentiment analysis of entries
- Track emotional patterns over time
- View past entries and emotional journey
- Receive insights on stress indicators, growth mindset, and self-reflection

**AI Analysis Capabilities:**

- **Sentiment Scoring:** Analyzes positive/negative emotional tone using NLTK's VADER
- **Pattern Detection:** Identifies stress indicators, relationship focus, growth mindset, and self-reflection
- **Emotional Tracking:** Monitors emotional trends over time

The journal feature is informed by research on expressive writing and emotional processing (Pennebaker, 1997; Smyth, 1998), which demonstrates the therapeutic benefits of written emotional expression. The AI sentiment analysis uses natural language processing techniques validated in computational psychology research (Calvo & D'Mello, 2010).

---

## 💭 Emotional Patterns Feature (Issue #269)

Allows users to describe their common emotional states, enabling more personalized and empathetic AI responses.

### How to Use

1. Navigate to **Profile → Strengths & Goals**
2. Scroll to the **"Emotional Profile"** section
3. Fill in your details:
   - **Common Emotional States**: Select or type emotions you often experience (e.g., Anxiety, Stress, Calmness)
   - **Emotional Triggers**: Describe what causes these emotions
   - **Coping Strategies**: Your personal methods for managing emotions
   - **Preferred AI Support Style**: How you want the AI to respond to you

### AI Support Styles

| Style                           | Response Approach                                          |
| ------------------------------- | ---------------------------------------------------------- |
| **Encouraging & Motivating**    | "You've got this! You've handled tough days before."       |
| **Problem-Solving & Practical** | "Here's an action item to try today..."                    |
| **Just Listen & Validate**      | "It's okay to feel this way. Take your time."              |
| **Distraction & Positivity**    | "Fun idea: Take a 5-min break and do something you enjoy!" |

### Integration

When you write journal entries, the AI will:

- Detect if your current emotional state matches your defined patterns
- Personalize responses based on your preferred support style
- Provide relevant coping suggestions from your profile

---

## 🤖 ML Model Training (Real User Data)

Soul Sense now supports training a custom Machine Learning model on **real local user data** to provide personalized risk assessments.

### How It Works

1.  **Data Collection**: As users take tests and write journals, data accumulates in `db/soulsense.db`.
2.  **Threshold**: The system requires at least **100 records** to ensure statistical validity.
3.  **Training**: The `train_real_model.py` script extracts this data, labels it based on risk factors (Score + Sentiment), and trains a Random Forest model.
4.  **Inference**: The app automatically uses the latest trained model for future predictions.

### Command to Train

```bash
python scripts/train_real_model.py
```

_Note: If you have fewer than 100 records, the script will abort to prevent overfitting._

### 📊 Data Distribution

The following chart emphasizes the quantity of data points across risk categories and score ranges used for training:

![Training Data Distribution](docs/images/training_data_distribution.png)

---

## 🧠 Sentiment Analysis Integration

### Overview

Soul Sense integrates **NLTK's VADER (Valence Aware Dictionary and sEntiment Reasoner)** sentiment analysis into both the EQ test and journal features, providing a more comprehensive understanding of users' emotional states.

### How It Helps Users

#### 1. **Captures Emotional Context Beyond Multiple Choice**

- MCQ questions only capture structured responses (Never/Sometimes/Often/Always)
- Open-ended reflection reveals **actual emotional state** in the user's own words
- Detects disconnect between quantitative scores and qualitative feelings

#### 2. **More Nuanced Risk Assessment**

The AI Analysis considers:

- **Quantitative data**: EQ scores (structured responses)
- **Qualitative data**: Sentiment score from written reflection (-100 to +100)

This dual analysis provides insights like:

- `High EQ + Negative Sentiment` = Good skills but currently struggling
- `Low EQ + Positive Sentiment` = Room for growth but good emotional resilience

#### 3. **Personalized Recommendations**

Based on sentiment ranges:

- **Negative (-20 to -100)**: Suggests journaling, professional support, stress management
- **Neutral (-20 to +20)**: Encourages continued practice
- **Positive (+20 to +100)**: Reinforces strengths, suggests mentorship

#### 4. **Validation & Empathy**

- Users feel heard when their written reflection is analyzed
- System acknowledges current emotional state
- Creates more human interaction vs. just numbers

### Technical Implementation

**VADER Features:**

- ✅ Understands negation: "I am NOT happy" → negative
- ✅ Detects intensity: "devastatingly sad" vs. "a bit sad"
- ✅ Works on casual, everyday language
- ✅ Real-time analysis with no external API calls

### Where Results Are Shown

1. **Results Dashboard**: Displays sentiment score alongside EQ score
2. **AI Analysis Popup**: Comprehensive analysis with:
   - Risk level and confidence
   - Sentiment score interpretation
   - Top influencing factors
   - Personalized recommendations based on both EQ and sentiment
3. **Journal Analytics**: Tracks sentiment trends over time (when using Daily Journal)

---

## 🛡️ Startup Integrity Checks

SoulSense includes a self-diagnostic system that runs every time the application starts to ensure a stable environment.

### What it Validates

| Check                | Description                                    | Auto-Recovery                                |
| -------------------- | ---------------------------------------------- | -------------------------------------------- |
| **Config Integrity** | Validates `config.json` structure and keys.    | Restores defaults if missing or corrupt.     |
| **Required Files**   | Ensures `data/`, `logs/`, and `models/` exist. | Auto-creates missing directories.            |
| **Database Schema**  | Verifies all required tables and columns.      | Re-initializes schema if tables are missing. |

### How it Works

The system categorizes issues into:

- **Warnings**: Non-critical issues that were auto-recovered. The app notifies the user and proceeds.
- **Failures**: Critical issues that prevent the app from starting safely. The app shows a detailed error and exits gracefully.

This prevents common "ModuleNotFoundError" or "DatabaseError" crashes that users might encounter due to filesystem issues.

---

## 💾 Database Backup & Restore

SoulSense allows you to create and restore local backups of your data, protecting against accidental data loss.

### Features

- **Create Backups**: Snapshot your database with optional description
- **Restore Backups**: Return to any previous backup state
- **Safety Copy**: Automatic safety backup before restoration
- **Manage Backups**: View, list, and delete old backups

### How to Use

1. Navigate to **Settings** in the profile sidebar
2. Scroll to **"Data Backup"** section
3. Click **"💾 Manage Backups"**
4. Create new backups or restore from existing ones

### Backup Storage

Backups are stored in `data/backups/` with timestamped filenames:

```
soulsense_backup_20260120_001500_my_description.db
```

---

## ⚙️ Environment Configuration

SoulSense supports configuration via environment variables with the `SOULSENSE_*` prefix.

### Quick Setup

1. **Copy the example file:**

   ```bash
   copy .env.example .env
   ```

2. **Edit `.env`** to customize settings (optional)

### Supported Variables

| Variable                     | Type   | Default             | Description                                    |
| ---------------------------- | ------ | ------------------- | ---------------------------------------------- |
| `SOULSENSE_ENV`              | string | `development`       | Environment mode (development/production/test) |
| `SOULSENSE_DEBUG`            | bool   | `false`             | Enable debug logging                           |
| `SOULSENSE_LOG_LEVEL`        | string | `INFO`              | Log level (DEBUG/INFO/WARNING/ERROR)           |
| `SOULSENSE_DB_PATH`          | string | `data/soulsense.db` | Custom database file path                      |
| `SOULSENSE_ENABLE_JOURNAL`   | bool   | `true`              | Enable/disable journal feature                 |
| `SOULSENSE_ENABLE_ANALYTICS` | bool   | `true`              | Enable/disable analytics feature               |

### Configuration Priority

1. **Environment variables** (highest priority)
2. **`.env` file** (loaded automatically if present)
3. **`config.json`** file
4. **Built-in defaults** (lowest priority)

> **Note:** No configuration is required for normal usage. The application works out-of-the-box with sensible defaults.

---

## 🧪 Experimental Feature Flags

SoulSense includes a feature flag system for controlling experimental and beta features. This allows you to enable cutting-edge functionality before it becomes generally available.

### Available Flags

| Flag                     | Environment Variable                  | Description                                |
| ------------------------ | ------------------------------------- | ------------------------------------------ |
| `ai_journal_suggestions` | `SOULSENSE_FF_AI_JOURNAL_SUGGESTIONS` | AI-powered suggestions in the journal      |
| `advanced_analytics`     | `SOULSENSE_FF_ADVANCED_ANALYTICS`     | Predictive insights in analytics dashboard |
| `beta_ui_components`     | `SOULSENSE_FF_BETA_UI_COMPONENTS`     | Experimental UI layouts and components     |
| `ml_emotion_detection`   | `SOULSENSE_FF_ML_EMOTION_DETECTION`   | ML-based emotion detection from text       |
| `data_export_v2`         | `SOULSENSE_FF_DATA_EXPORT_V2`         | New export formats (PDF, enhanced CSV)     |

### Enabling a Feature

**Option 1: Environment Variable** (recommended for testing)

```bash
set SOULSENSE_FF_AI_JOURNAL_SUGGESTIONS=true
python -m app.main
```

**Option 2: `.env` File**

```bash
SOULSENSE_FF_AI_JOURNAL_SUGGESTIONS=true
```

**Option 3: `config.json`**

```json
{
  "experimental": {
    "ai_journal_suggestions": true
  }
}
```

**Option 3: `Direct`**

```bash
Turn on
$env:SOULSENSE_FF_AI_JOURNAL_SUGGESTIONS = "true"
Turn Off
$env:SOULSENSE_FF_AI_JOURNAL_SUGGESTIONS = "false"
python -m app.main
```

### Python API for Developers

```python
from app.feature_flags import feature_flags, feature_gated

# Check if a flag is enabled
if feature_flags.is_enabled("ai_journal_suggestions"):
    # Use experimental feature
    pass

# Use decorator to gate entire functions
@feature_gated("ml_emotion_detection")
def detect_emotions(text):
    # Only runs if flag is enabled
    return model.predict(text)
```

> **Warning:** Experimental features may change or be removed without notice.

---

## 🛠 Technologies Used

- Python 3.11+
- Tkinter (GUI)
- SQLite3 (Database)
- Pytest (Testing)

---

## 📂 Project Structure (Refactored)

```bash
SOUL_SENSE_EXAM/
│
├── app/                     # Core application package
│   ├── ml/                  # Machine Learning modules
│   │   ├── __init__.py
│   │   ├── predictor.py
│   │   ├── clustering.py
│   │   └── ...
│   ├── ui/                  # UI components
│   │   ├── dashboard.py
│   │   ├── journal.py
│   │   └── ...
│   ├── main.py              # Tkinter application entry point
│   ├── config.py            # Centralized configuration
│   ├── db.py                # Database connection & migrations
│   ├── i18n_manager.py      # Internationalization
│   └── ...
│
├── data/                    # persistent data
│   ├── soulsense.db         # SQLite database
│   ├── questions.txt        # Source question bank
│   └── experiments/         # ML experiments
│
├── models/                  # ML models & registry
│   ├── soulsense_ml_model.pkl
│   └── registry/
│
├── logs/
│   └── soulsense.log        # Application logs
│
├── scripts/                 # Maintenance scripts
├── tests/                   # Pytest test suite
├── migrations/              # Alembic migrations
│
├── alembic.ini              # Alembic config
├── pytest.ini               # Pytest config
├── requirements.txt         # Dependencies
└── README.md
```

---

## 🧩 Question Format

Each question is rated on a 4-point Likert scale:

- Never (1)
- Sometimes (2)
- Often (3)
- Always (4)

### Sample Questions

- You can recognize your emotions as they happen.
- You adapt well to changing situations.
- You actively listen to others when they speak.

---

## 🐍 Setting Up a Virtual Environment & Installing Packages

It’s recommended to use a **virtual environment** to keep your project dependencies isolated from your system Python.

1️⃣ Create a Virtual Environment  
From your project root directory:

```bash
python -m venv venv
```

This will create a `venv/` folder inside your project.

2️⃣ Activate the Virtual Environment

Windows:

```bash
venv\Scripts\activate
```

macOS/Linux:

```bash
source venv/bin/activate
```

When active, your terminal prompt will show `(venv)`.

3️⃣ Install Required Packages

Once activated, install your project dependencies:

```bash
pip install -r requirements.txt
```

<!--4️⃣ Save Dependencies (Optional but Recommended)

Freeze installed packages to a `requirements.txt` file:
pip freeze > requirements.txt

Later, to replicate the environment on another machine:
pip install -r requirements.txt -->

> Always **activate the virtual environment** before running scripts or installing new packages.

✅ Tip: If you see `ModuleNotFoundError`, it usually means your virtual environment is **not active** or the package isn’t installed inside it.

---

## ▶️ How to Run

### 1. Unified Setup

Initialize database, seed data, and run all feature migrations in one step:

```bash
python -m scripts.setup_dev
```

### 4. Start the Application

Launch the SoulSense interface:

```bash
python -m app.main
```

## 🛠️ Troubleshooting & Developer Notes

### Common Issues & Fixes

1.  **"Failed to fetch questions from DB" / `KeyError: min_age`**
    - **Cause**: Database schema is outdated (missing columns in `QuestionCache`).
    - **Fix**: Run migration or reset database:
      ```bash
      python -m scripts.fix_db
      python -m scripts.load_questions
      ```

2.  **`ImportError: cannot import name 'get_session' from 'app.models'`**
    - **Fix**: This project strictly separates DB connection logic (`app.db`) from models (`app.models`). Ensure you import `get_session` from `app.db`.

3.  **Application Freeze on Startup**
    - **Cause**: Matplotlib trying to use an interactive backend (TkAgg) conflicting with Tkinter main loop.
    - **Fix**: Ensure `matplotlib.use('Agg')` is called _before_ importing `pyplot`.

4.  **`ObjectNotExecutableError`**
    - **Cause**: SQLAlchemy 2.0+ requires raw SQL to be wrapped in `text()`.
    - **Fix**: Use `from sqlalchemy import text` and wrap strings: `connection.execute(text("SELECT ..."))`.

### For Contributors

- Always install new dependencies via `pip install -r requirements.txt`.
- If you change the database models, generate a migration: `python -m alembic revision --autogenerate -m "message"`.
- This project uses **SQLAlchemy 2.0** syntax. Avoid legacy query patterns.

> **Note:** Do not use `npm run dev`. This is a pure Python application.

**Authentication Flow:**

1. **First-time users:** Click "Sign Up" to create an account
   - Choose a username (minimum 3 characters)
   - Set a password (minimum 4 characters)
   - Confirm your password

2. **Returning users:** Enter your username and password to login

3. **During the test:** Use the logout button to switch users or exit securely

**Security Features:**

- Passwords are hashed using bcrypt with 12 rounds
- Legacy SHA-256 passwords are automatically upgraded on login
- User sessions are managed securely
- Each user's data is isolated and protected

---

## 🧪 Automated Testing & CI/CD

We maintain a comprehensive test suite to ensure application stability.

### 1. Running Tests Locally

Run the full test suite with:

```bash
python -m pytest tests/ -v
```

This executes:

- **Unit Tests**: Verifies UI logic (auth, exam flow) using mocks.
- **Integration Tests**: Verifies database schemas and clustering logic.
- **Migration Tests**: Verifies `alembic upgrade head` works on a fresh DB.

### 2. Continuous Integration (GitHub Actions)

This project uses **GitHub Actions** for CI. Every push to `main` or Pull Request triggers:

- **Linting**: `flake8` checks for code style issues.
- **Testing**: `pytest` runs the full suite in a headless environment.

Configuration file: `.github/workflows/python-app.yml`

### 3. Database Migrations

We use **Alembic** for safe database schema updates.

**Apply Migrations:**

```bash
python -m alembic upgrade head
```

**Create New Migration (after modifying models):**

```bash
python -m alembic revision --autogenerate -m "describe_change"
```

**Verify Migrations:**
Our test suite includes `tests/test_migrations.py` which guarantees that migrations apply correctly to a fresh database.

### 4. Test Fixtures (Issue #348)

SoulSense provides a comprehensive test fixture system for standardized, reusable test data.

**Available Fixtures:**

| Category              | Fixtures                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Database Entities** | `sample_user`, `sample_user_with_profiles`, `sample_score`, `sample_responses`, `sample_journal_entry`, `sample_question_bank` |
| **ML Components**     | `sample_user_features`, `sample_clustered_features`, `mock_clusterer`, `mock_feature_extractor`, `mock_risk_predictor`         |
| **Utilities**         | `temp_db` (isolated database), `isolated_db`, `populated_db`                                                                   |

**Factory Classes:**

```python
from tests.fixtures import UserFactory, ScoreFactory, FeatureDataFactory

# Create test user with all profiles
user = UserFactory.create_with_profiles(session)

# Create batch of scores
scores = ScoreFactory.create_batch(session, user, count=10)

# Generate ML feature data
features = FeatureDataFactory.create_user_features(n_users=50)
```

**Using Fixtures in Tests:**

```python
def test_user_scores(temp_db, sample_user):
    """Fixtures are automatically available to all tests."""
    from tests.fixtures import ScoreFactory
    scores = ScoreFactory.create_batch(temp_db, sample_user, count=5)
    assert len(scores) == 5
```

For complete documentation, see [tests/FIXTURES.md](tests/FIXTURES.md).

---

## 📊 Outlier Detection Features

### Overview

The outlier detection module identifies extreme or inconsistent emotional intelligence scores using advanced statistical methods.

**Supported Methods:**

- **Z-Score**: Identifies scores deviating significantly from mean
- **IQR (Interquartile Range)**: Robust method for skewed distributions
- **Modified Z-Score**: Uses median/MAD for robustness
- **MAD (Median Absolute Deviation)**: Resistant to extreme values
- **Ensemble**: Consensus-based approach combining multiple methods

### Command Line Usage

```bash
# Analyze user scores
python scripts/outlier_analysis.py --user john_doe --method ensemble

# Analyze age group
python scripts/outlier_analysis.py --age-group "18-25" --method iqr

# Global analysis
python scripts/outlier_analysis.py --global --method zscore

# Check inconsistency patterns
python scripts/outlier_analysis.py --inconsistency john_doe --days 30

# Get statistics
python scripts/outlier_analysis.py --stats --age-group "26-35"

# Output as JSON
python scripts/outlier_analysis.py --user john_doe --format json
```

### Python API

```python
from app.db import get_session
from app.analysis.outlier_detection import OutlierDetector

detector = OutlierDetector()
session = get_session()

# Detect outliers for user
result = detector.detect_outliers_for_user(session, "john_doe", method="ensemble")

# Detect by age group
result = detector.detect_outliers_by_age_group(session, "18-25", method="iqr")

# Global analysis
result = detector.detect_outliers_global(session, method="zscore")

# Inconsistency analysis
result = detector.detect_inconsistency_patterns(session, "john_doe", time_window_days=30)
```

---

## 🧱 Design Notes

- Database schemas are created and migrated safely at runtime
- Question loading is idempotent and separated from application logic
- Core logic is decoupled from the GUI to enable testing
- Outlier detection uses NumPy for efficient statistical computations
- All methods are fully tested with comprehensive edge case coverage

---

## 📌 Status

- Refactor complete
- Tests added
- Stable baseline for further enhancements (e.g., decorators, generators)

## 🤝 Contributing

We welcome contributions from the community.  
Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing to help maintain a respectful and inclusive environment.