# Installation Guide

## 1. Requirements

- Python 3.10+
- MySQL 8.0+ (for production/staging) — or nothing extra for local dev, since
  the app defaults to a local SQLite file
- Node is only needed if you want to serve the frontend with a dev server;
  a plain static file server (or even opening `index.html` directly) works

## 2. Clone and install Python dependencies

```bash
cd mindscreen_ai
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r backend/requirements.txt
```

The `mindscreen/` package (chatbot, questionnaires, NLP, risk engine) has no
extra dependencies beyond `numpy` and `scikit-learn`, which are already in
`backend/requirements.txt`.

## 3. Configure environment variables

```bash
cp backend/.env.example backend/.env
```

Edit `backend/.env`:

- **Local development (default, zero-config):** leave `DATABASE_URL` as the
  SQLite default. Nothing else to do.
- **MySQL (staging/production):**
  ```bash
  DATABASE_URL=mysql+pymysql://mindscreen_user:CHANGE_ME@localhost:3306/mindscreen_ai
  ```
  First create the database and load the schema:
  ```bash
  mysql -u root -p < database/schema.sql
  ```
  (The FastAPI app can also auto-create tables via SQLAlchemy on startup —
  `database/schema.sql` is provided for explicit DBA review/versioning and
  matches the ORM models field-for-field.)

- **JWT secret:** set `JWT_SECRET_KEY` to a long random string in any
  non-local environment. Never commit real secrets.

- **Email verification:** leave `EMAIL_SENDING_ENABLED=false` for local dev
  — verification links are logged to the console instead of emailed. Set to
  `true` and fill in `SMTP_*` for real email sending.

Environment variables are loaded by `backend/config.py`. If you use a
`.env` loader like `python-dotenv`, add `load_dotenv()` at the top of
`backend/main.py`, or simply `export` the variables in your shell/deploy
environment.

## 4. Run the backend

```bash
# From the mindscreen_ai/ project root:
uvicorn backend.main:app --reload
```

- API root: http://localhost:8000
- Interactive docs: http://localhost:8000/docs
- Health check: http://localhost:8000/health

On first run, tables are created automatically (SQLite or MySQL, whichever
`DATABASE_URL` points to).

## 5. (Optional) Seed sample data

Populates ~15 synthetic demo users/sessions so the dashboard has data to show:

```bash
python3 -m database.seed_data
```

## 6. Serve the frontend

The frontend is plain HTML/CSS/JS with no build step.

```bash
cd frontend
python3 -m http.server 3000
```

Open http://localhost:3000. If your backend isn't on `localhost:8000`, set
the base URL before `app.js` loads by adding this to `index.html`:

```html
<script>window.MINDSCREEN_API_BASE = "https://your-api-host.example.com";</script>
<script src="app.js"></script>
```

Also update `ALLOWED_ORIGINS` in `backend/.env` to include the frontend's
origin (CORS).

## 7. Run the core-logic test suite

```bash
python3 -m unittest discover -s mindscreen/tests -p "test_*.py" -v
```

These 28 tests cover questionnaire scoring, NLP analysis, safety detection,
the risk engine, and full conversation flows — and run with zero extra
dependencies (no FastAPI/DB needed).

## 8. Production notes (not fully implemented in this build)

- Add a researcher/admin role before exposing `/dashboard/*` beyond dev use.
- Move `ConversationManager` in-memory session state to a shared store
  (Redis, or reconstruct-from-DB) if running multiple server workers.
- Put a real reverse proxy / HTTPS in front of uvicorn (e.g. via Caddy, or
  `uvicorn --ssl-keyfile ... --ssl-certfile ...` behind nginx).
- Replace `Base.metadata.create_all()` with Alembic migrations once the
  schema is stable.
- Expand the NLP lexicons / retrain `MLRiskClassifier` on real, consented,
  IRB-approved labeled data before any non-demo use.