diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..ab556e9
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,29 @@
+version: 2
+updates:
+ # Frontend (root package.json)
+ - package-ecosystem: "npm"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "08:00"
+ open-pull-requests-limit: 10
+ groups:
+ dev-dependencies:
+ dependency-type: "development"
+ production-dependencies:
+ dependency-type: "production"
+
+ # Backend
+ - package-ecosystem: "npm"
+ directory: "/backend"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "08:00"
+ open-pull-requests-limit: 10
+ groups:
+ backend-dev:
+ dependency-type: "development"
+ backend-prod:
+ dependency-type: "production"
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
new file mode 100644
index 0000000..c030d60
--- /dev/null
+++ b/.github/workflows/security.yml
@@ -0,0 +1,76 @@
+name: Security Audit
+
+on:
+ push:
+ branches: [main, pre-deployment]
+ pull_request:
+ branches: [main]
+ schedule:
+ # Every Monday at 08:00 UTC
+ - cron: '0 8 * * 1'
+
+jobs:
+ audit-frontend:
+ name: Frontend — npm audit
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Run audit (fail on high+)
+ run: npm audit --audit-level=high
+
+ audit-backend:
+ name: Backend — npm audit
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+ cache-dependency-path: backend/package-lock.json
+
+ - name: Install backend dependencies
+ working-directory: backend
+ run: npm ci
+
+ - name: Run audit (fail on high+)
+ working-directory: backend
+ run: npm audit --audit-level=high
+
+ typecheck:
+ name: TypeScript — type check
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Type check frontend
+ run: npx tsc --noEmit
+
+ - name: Install backend deps
+ working-directory: backend
+ run: npm ci
+
+ - name: Type check backend
+ working-directory: backend
+ run: npx tsc --noEmit
diff --git a/.gitignore b/.gitignore
index 341517a..b2c79d1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,4 +3,6 @@
node_modules
dist
.DS_Store
-backend/prisma/schema.prisma
\ No newline at end of file
+backend/prisma/schema.prisma
+backups/
+*.log
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..989c87f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,150 @@
+# OpenStudbook — Dev Environment
+
+## Stack
+
+| Layer | Tool | Port |
+|---|---|---|
+| Frontend | Vite (React + TypeScript) | 3000 |
+| Backend | Express + ts-node-dev | 3001 |
+| Database | MySQL | 3306 |
+| Mail catcher | maildev | SMTP 1025 · Web UI 1080 |
+
+## Starting the dev environment
+
+### 1. Backend
+```bash
+cd backend && npm run dev
+```
+
+### 2. Frontend
+```bash
+npm run dev
+```
+
+### 3. Mail catcher (maildev)
+```bash
+maildev --smtp 1025 --web 1080
+```
+Web UI: http://localhost:1080
+All outbound emails are caught here — nothing reaches real inboxes.
+
+> maildev is installed as a global npm package:
+> `npm install -g maildev`
+
+### 4. Cloudflare tunnel (public URL)
+```bash
+npm run tunnel
+```
+Or directly:
+```bash
+"C:\Program Files (x86)\cloudflared\cloudflared.exe" tunnel --url http://localhost:3000 --no-autoupdate
+```
+The public `trycloudflare.com` URL is printed to the console on startup.
+
+## SMTP settings (stored in DB `app_config`)
+
+| Key | Value |
+|---|---|
+| smtpHost | localhost |
+| smtpPort | 1025 |
+| smtpUser | (empty) |
+| smtpPass | (empty) |
+| smtpSecure | false |
+
+These match maildev's defaults — no changes needed for local dev.
+
+## Environment variables
+
+Backend reads from `backend/.env`:
+
+```
+PORT=3001
+JWT_SECRET=...
+API_KEY=...
+DATABASE_HOST=localhost
+DATABASE_PORT=3306
+DATABASE_USER=root
+DATABASE_PASSWORD=...
+DATABASE_NAME=openstudbook
+```
+
+## Cloudflare tunnel
+
+The `npm run tunnel` script uses the locally installed `cloudflared` at:
+`C:\Program Files (x86)\cloudflared\cloudflared.exe`
+
+For ngrok instead: `npm run ngrok`
+
+---
+
+## Security Maintenance Plan
+
+### Automated (no action needed once set up)
+
+| What | How | Cadence |
+|---|---|---|
+| Dependency vulnerability PRs | GitHub Dependabot (`.github/dependabot.yml`) | Weekly — Mondays |
+| `npm audit` gate on PRs | GitHub Actions (`.github/workflows/security.yml`) | Every push to `main` / `pre-deployment` |
+| TypeScript type-check gate | GitHub Actions (same workflow) | Every push |
+| Database backup | Windows Scheduled Task → `scripts/backup-db.ps1` | Nightly at 02:00 |
+| Backup pruning | Built into `backup-db.ps1` | Nightly (keeps 30 days) |
+
+**First-time setup for the scheduled backup task:**
+```powershell
+# Run once as Administrator
+powershell -ExecutionPolicy Bypass -File scripts\register-scheduled-tasks.ps1
+```
+Backups are written to `backups/` as `.sql.gz` files (excluded from git via `.gitignore`).
+
+---
+
+### Manual — Quarterly Checklist
+
+**Credentials**
+- [ ] Rotate `JWT_SECRET` in `backend/.env` and restart backend (invalidates all sessions — users re-login)
+- [ ] Rotate `DATABASE_PASSWORD` in MariaDB and `backend/.env`
+- [ ] Rotate `API_KEY` (Gemini) if shared or potentially exposed
+- [ ] Review any per-org Gemini API keys stored in the DB
+
+**Dependencies**
+- [ ] Run `npm audit` in root and `backend/` — fix anything at high or critical severity
+- [ ] Review and merge pending Dependabot PRs
+
+**Access**
+- [ ] Audit Super Admin accounts — remove any that are no longer needed
+- [ ] Review active user sessions / tokens (no server-side session store currently — rotating JWT_SECRET covers this)
+
+**Infrastructure**
+- [ ] Verify nightly backups are succeeding (`backups/backup.log`)
+- [ ] Test a backup restore against a spare DB instance
+- [ ] Check MariaDB version — upgrade if a security release is available
+
+---
+
+### Known Hardening Items (implement before public deployment)
+
+These are not yet in the codebase and should be addressed before exposing the app to the internet:
+
+| Priority | Issue | Fix |
+|---|---|---|
+| 🔴 High | CORS is `origin: '*'` | Lock to your actual domain in `backend/src/index.ts` |
+| 🔴 High | No HTTP security headers | Add `helmet` middleware (`npm install helmet`) |
+| 🔴 High | No rate limiting on auth endpoints | Add `express-rate-limit` on `/api/login`, `/api/register`, `/api/forgot-password` |
+| 🟡 Medium | JWT secret is a static string | Use a long random secret (32+ chars) and rotate quarterly |
+| 🟡 Medium | `express.json` body limit is 50 MB | Reduce to `5mb` unless large uploads are needed |
+| 🟢 Low | Morgan logs to console only | Pipe to a file with log rotation in production |
+
+---
+
+### Backups
+
+Backups are stored in `backups/` (gitignored). The script uses MariaDB's `mysqldump` with `--single-transaction` for a consistent snapshot.
+
+To restore a backup:
+```powershell
+# Decompress
+Expand-Archive backups\openstudbook_2026-01-01_02-00-00.sql.gz -DestinationPath backups\
+
+# Restore
+& "C:\Program Files\MariaDB 12.2\bin\mysql.exe" -u root -p openstudbook < backups\openstudbook_2026-01-01_02-00-00.sql
+```
diff --git a/README.md b/README.md
index af657e3..c796a55 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,361 @@
-
+
+
+# OpenStudbook
+
+**Open-source captive breeding and botanical collection management for zoos, aquariums, and botanical gardens.**
+
+[](https://github.com/teruselearning/openstud/actions/workflows/security.yml)
+[](LICENSE)
+
-# Run and deploy your AI Studio app
+---
+
+OpenStudbook is a self-hosted web platform for managing captive animal and plant populations. Track individuals, species, breeding events, genetic lineage, health records, and enclosures — with a global network map for inter-organisation partnerships.
+
+**Key features:**
+- 🐾 **Fauna & Flora modes** — unified management for animals and plants
+- 🧬 **Studbook & genetics** — lineage tracking, breeding recommendations, DNA records
+- 🌍 **Network map** — discover partner organisations and propose breeding loans
+- 🤖 **AI assist** — species autofill and illustration via Gemini (optional)
+- 🔒 **Multi-factor auth**, per-org user roles, and full data export
+- 🌐 **Multi-language** — 10+ languages with live AI translation
+
+---
+
+## Contents
+
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Running the Dev Environment](#running-the-dev-environment)
+- [First-Time Setup (Installer)](#first-time-setup-installer)
+- [Production Deployment](#production-deployment)
+- [Resetting the Database](#resetting-the-database)
+- [Optional: AI Features](#optional-ai-features)
+- [Optional: Cloudflare / ngrok Tunnel](#optional-cloudflare--ngrok-tunnel)
+- [Security](#security)
+- [Contributing](#contributing)
+
+---
+
+## Requirements
+
+| Dependency | Minimum version | Notes |
+|---|---|---|
+| Node.js | 18 LTS | 20 LTS recommended |
+| npm | 9+ | Bundled with Node |
+| MariaDB **or** MySQL | MariaDB 10.6+ / MySQL 8.0+ | Must support `utf8mb4` |
+
+> **Windows users:** [MariaDB MSI installer](https://mariadb.org/download/) is the easiest option.
+> **macOS users:** `brew install mariadb && brew services start mariadb`
+> **Linux users:** `sudo apt install mariadb-server` or equivalent.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Clone
+git clone https://github.com/teruselearning/openstud.git
+cd openstud
+
+# 2. Install frontend dependencies
+npm install
+
+# 3. Install backend dependencies
+cd backend && npm install && cd ..
+
+# 4. Configure environment
+cp backend/.env.example backend/.env
+# → open backend/.env and fill in your DB credentials and JWT secret
+
+# 5. Create the database
+# (MariaDB / MySQL must be running)
+mysql -u root -p -e "CREATE DATABASE openstudbook CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+
+# 6. Start the backend
+cd backend && npm run dev &
+
+# 7. Start the frontend (new terminal)
+npm run dev
+```
+
+Then open **http://localhost:3000** — the installer wizard will guide you through creating your first organisation and admin account.
+
+---
+
+## Configuration
+
+All backend configuration lives in `backend/.env`. Copy the example file and edit it:
+
+```bash
+cp backend/.env.example backend/.env
+```
+
+| Variable | Required | Description |
+|---|---|---|
+| `PORT` | No | Backend port (default: `3001`) |
+| `JWT_SECRET` | **Yes** | Long random string used to sign auth tokens. Generate one: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` |
+| `DATABASE_HOST` | **Yes** | DB host (usually `localhost`) |
+| `DATABASE_PORT` | No | DB port (default: `3306`) |
+| `DATABASE_USER` | **Yes** | DB username |
+| `DATABASE_PASSWORD` | **Yes** | DB password |
+| `DATABASE_NAME` | **Yes** | DB name (e.g. `openstudbook`) |
+| `API_KEY` | No | Gemini API key — enables AI species autofill and illustrations. [Get one free.](https://aistudio.google.com/) |
+
+> **Never commit `backend/.env`** — it is gitignored by default.
+
+---
+
+## Running the Dev Environment
+
+You need four processes running simultaneously. Open a separate terminal for each:
+
+### 1. Backend (Express + TypeScript)
+
+```bash
+cd backend
+npm run dev
+# Listening on http://localhost:3001
+```
+
+### 2. Frontend (Vite + React)
+
+```bash
+npm run dev
+# Listening on http://localhost:3000
+```
+
+### 3. Mail catcher (optional — catches outbound emails locally)
+
+OpenStudbook sends transactional emails (invitations, password reset, MFA codes). In development, catch them locally instead of sending to real inboxes.
+
+**Using [maildev](https://github.com/maildev/maildev)** (recommended):
+
+```bash
+# Install once
+npm install -g maildev
+
+# Run
+maildev --smtp 1025 --web 1080
+```
+
+Web UI → **http://localhost:1080**
+
+Then set these values in the Super Admin → SMTP settings panel:
+
+| Setting | Value |
+|---|---|
+| SMTP Host | `localhost` |
+| SMTP Port | `1025` |
+| SMTP User | *(empty)* |
+| SMTP Pass | *(empty)* |
+| Secure (TLS) | Off |
+
+### 4. Cloudflare tunnel (optional — gives your local app a public HTTPS URL)
+
+Useful for testing on mobile devices or sharing a preview.
+
+```bash
+npm run tunnel
+```
+
+The public `trycloudflare.com` URL is printed to the console. Requires [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed at `C:\Program Files (x86)\cloudflared\cloudflared.exe`.
+
+---
+
+## First-Time Setup (Installer)
+
+On a **fresh database**, the app automatically shows the installation wizard at **http://localhost:3000**.
+
+The wizard will ask you to:
+
+1. **Test the database connection** — verifies the credentials in `backend/.env` are working
+2. **Create your organisation** — name and admin account details
+3. **Choose a focus** — Fauna (animals) or Flora (plants)
-This contains everything you need to run your app locally.
+After setup, you can configure SMTP, languages, branding, and feature flags under **Super Admin** (the gear icon in the sidebar).
-View your app in AI Studio: https://ai.studio/apps/drive/1X_Gb2pzUHZHt4rb716OtG_QhLJrPbSU7
+> If you need to re-run the installer (e.g. for testing), see [Resetting the Database](#resetting-the-database).
-## Run Locally
+---
-**Prerequisites:** Node.js
+## Production Deployment
+OpenStudbook is designed to run on a single Linux/Windows server behind a reverse proxy.
-1. Install dependencies:
- `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
- `npm run dev`
+### Recommended stack
+
+```
+Internet → Nginx (HTTPS/TLS) → Vite static build (port 80)
+ → Express backend (port 3001)
+```
+
+### Build steps
+
+```bash
+# Build the frontend
+npm run build
+# Output is in dist/ — serve as static files via Nginx
+
+# Build the backend
+cd backend && npm run build
+# Output is in backend/dist/ — run with: node dist/index.js
+```
+
+### Nginx example config
+
+```nginx
+server {
+ listen 443 ssl;
+ server_name yourdomain.com;
+
+ # SSL cert (e.g. Let's Encrypt)
+ ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
+ ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
+
+ # Frontend (built static files)
+ root /var/www/openstudbook/dist;
+ index index.html;
+ try_files $uri $uri/ /index.html;
+
+ # Backend API proxy
+ location /api/ {
+ proxy_pass http://localhost:3001;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ }
+
+ location /rest/ {
+ proxy_pass http://localhost:3001;
+ }
+
+ location /uploads/ {
+ proxy_pass http://localhost:3001;
+ }
+}
+
+# Redirect HTTP → HTTPS
+server {
+ listen 80;
+ server_name yourdomain.com;
+ return 301 https://$host$request_uri;
+}
+```
+
+### Environment for production
+
+Update `backend/.env` for production:
+
+```
+NODE_ENV=production
+PORT=3001
+JWT_SECRET=
+DATABASE_HOST=localhost
+DATABASE_USER=openstudbook_user
+DATABASE_PASSWORD=
+DATABASE_NAME=openstudbook
+```
+
+### Process management (Linux)
+
+```bash
+# Install pm2
+npm install -g pm2
+
+# Start backend
+pm2 start backend/dist/index.js --name openstudbook-api
+
+# Auto-restart on reboot
+pm2 startup
+pm2 save
+```
+
+### Before going public — security checklist
+
+- [ ] Lock CORS in `backend/src/index.ts`: change `origin: '*'` to your domain
+- [ ] Add `helmet` middleware: `npm install helmet` → `app.use(helmet())`
+- [ ] Add rate limiting on auth endpoints: `npm install express-rate-limit`
+- [ ] Use a strong, unique `JWT_SECRET` (32+ random characters)
+- [ ] Restrict DB user permissions — grant only `SELECT, INSERT, UPDATE, DELETE` on `openstudbook`
+- [ ] Enable HTTPS — use Let's Encrypt / Certbot
+- [ ] Disable `enableRegistration` in Super Admin if you don't want public sign-ups
+
+---
+
+## Resetting the Database
+
+Useful during development or to re-run the installer wizard.
+
+**MariaDB / MySQL:**
+
+```bash
+mysql -u root -p -e "DROP DATABASE openstudbook; CREATE DATABASE openstudbook CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+```
+
+Then restart the backend — it will re-run migrations and show the installer on next page load.
+
+---
+
+## Optional: AI Features
+
+OpenStudbook integrates with [Google Gemini](https://aistudio.google.com/) for:
+
+- **Species autofill** — fill conservation status, lifespan, weight from scientific name
+- **AI illustration** — generate a representative species image
+- **Language translation** — auto-translate UI strings into new languages
+
+To enable, add your key to `backend/.env`:
+
+```
+API_KEY=your_gemini_api_key_here
+```
+
+AI usage is tracked per organisation and capped by the Super Admin. Organisations can also provide their own Gemini API key in Org Settings to bypass the shared limit.
+
+---
+
+## Optional: Cloudflare / ngrok Tunnel
+
+Expose your local dev instance publicly (useful for mobile testing, demos, or webhook testing).
+
+**Cloudflare Quick Tunnel** (no account needed):
+```bash
+npm run tunnel
+```
+
+**ngrok** (requires free account):
+```bash
+npm run ngrok
+```
+
+Both print a public HTTPS URL to the console.
+
+---
+
+## Security
+
+See the [security maintenance plan in CLAUDE.md](CLAUDE.md#security-maintenance-plan) for the full automated and manual security schedule.
+
+To report a vulnerability, please open a [GitHub Security Advisory](https://github.com/teruselearning/openstud/security/advisories/new) rather than a public issue.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repo and create a feature branch from `main`
+2. Run `npm audit` in both root and `backend/` — no new high/critical issues
+3. Test the installer flow on a fresh database before submitting
+4. Open a pull request against `main` with a clear description of the change
+
+For larger changes, open an issue first to discuss the approach.
+
+---
+
+
+ Built with ❤️ for wildlife conservation and botanical management.
+