# Command Sovereignty — Project Context
## Critical Paths (DO NOT GUESS)
| What | Path | Notes |
|---|---|---|
| SQLite DB | `instance/auth.db` | **NOT** `auth.db` at root. App reads `instance/auth.db` only. |
| Env config | `~/.config/command-sovereignty/env` | `DATABASE_URL` pinned here. |
| Backups | `backups/auth_YYYYMMDD_HHMMSS.db.gz` | Managed by `scripts/backup_db.sh` (cron every 6h). |
| Backup script | `scripts/backup_db.sh` | Points to `instance/auth.db` with fallback to root. |
| Venv | `.venv/` | Python 3.11, Flask + SQLAlchemy. |
| Frontend | `frontend/` | Vite 8 / React / TypeScript. Build: `node node_modules/vite/bin/vite.js build`. |
| Logs | `logs/app.log` | Rotating file logger. |
| Service | `systemctl --user command-sovereignty.service` | Gunicorn on port 5003. |
| Production URL | `builtdomains.com` | Cloudflare tunnel → localhost:5003. |
## Database Rules
1. **NEVER** run `db.create_all()` without first verifying `instance/auth.db` has data.
2. **NEVER** run `db.drop_all()` — there is no migration system to recover from it.
3. Before touching the DB, check: `sqlite3 instance/auth.db "SELECT count(*) FROM profiles;"`
4. If profiles count is 0, **stop** and restore from `backups/` instead.
5. The backup script validates the DB has rows before backing up — check its output.
## Common Pitfalls
- **Two DB files trap:** An old `auth.db` used to exist at the project root. It was deleted July 2026. Always use `instance/auth.db`.
- **SESSION_COOKIE_SECURE=true** is set in env — cookies won't work on localhost HTTP, only HTTPS via Cloudflare.
- **Vite build quirk:** `npx vite build` falsely triggers terminal background detection. Use `node node_modules/vite/bin/vite.js build` instead.
- **Login is cookie-based** (Flask-Login sessions), NOT JWT tokens. Frontend sends cookies.
- **Auth model:** `User` table is `profiles` in SQLite.
## Service Commands
```bash
# Restart after code changes
systemctl --user restart command-sovereignty.service
# Check status
systemctl --user status command-sovereignty.service
# View logs
tail -50 logs/app.log
# Test backup
bash scripts/backup_db.sh
```