phase 3 done

docs/WEB_QUICKSTART.md

@@ -0,0 +1,252 @@
+# Web Platform Quick Start
+
+## Prerequisites
+
+- PostgreSQL database running
+- Python 3.10+
+- Environment configured (`.env` file)
+
+---
+
+## Installation
+
+### 1. Install Web Dependencies
+
+```bash
+pip install fastapi uvicorn
+```
+
+### 2. Configure Environment
+
+Add to your `.env` file:
+
+```env
+# Required
+DATABASE_URL=postgresql://user:pass@localhost:5432/loyal_companion
+
+# Web Platform
+WEB_ENABLED=true
+WEB_HOST=127.0.0.1
+WEB_PORT=8080
+
+# Optional
+WEB_CORS_ORIGINS=["http://localhost:3000", "http://localhost:8080"]
+WEB_RATE_LIMIT=60
+```
+
+---
+
+## Running the Web Server
+
+### Development Mode
+
+```bash
+python3 run_web.py
+```
+
+Server will start at: **http://127.0.0.1:8080**
+
+### Production Mode
+
+```bash
+uvicorn loyal_companion.web:app \
+  --host 0.0.0.0 \
+  --port 8080 \
+  --workers 4
+```
+
+---
+
+## Using the Web UI
+
+1. **Open browser:** Navigate to `http://localhost:8080`
+
+2. **Enter email:** Type any email address (e.g., `you@example.com`)
+   - For Phase 3, any valid email format works
+   - No actual email is sent
+   - Token is generated as `web:your@example.com`
+
+3. **Start chatting:** Type a message and press Enter
+   - Shift+Enter for new line
+   - Conversation is saved automatically
+   - Refresh page to load history
+
+---
+
+## API Usage
+
+### Get Authentication Token
+
+```bash
+curl -X POST http://localhost:8080/api/auth/token \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@example.com"}'
+```
+
+Response:
+```json
+{
+  "message": "Token generated successfully...",
+  "token": "web:test@example.com"
+}
+```
+
+### Send Chat Message
+
+```bash
+curl -X POST http://localhost:8080/api/chat \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer web:test@example.com" \
+  -d '{
+    "session_id": "my_session",
+    "message": "Hello, how are you?"
+  }'
+```
+
+Response:
+```json
+{
+  "response": "Hey there. I'm here. How are you doing?",
+  "mood": {
+    "label": "neutral",
+    "valence": 0.0,
+    "arousal": 0.0,
+    "intensity": 0.3
+  },
+  "relationship": {
+    "level": "stranger",
+    "score": 5,
+    "interactions_count": 1
+  },
+  "extracted_facts": []
+}
+```
+
+### Get Conversation History
+
+```bash
+curl http://localhost:8080/api/sessions/my_session/history \
+  -H "Authorization: Bearer web:test@example.com"
+```
+
+### Health Check
+
+```bash
+curl http://localhost:8080/api/health
+```
+
+---
+
+## API Documentation
+
+FastAPI automatically generates interactive API docs:
+
+- **Swagger UI:** http://localhost:8080/docs
+- **ReDoc:** http://localhost:8080/redoc
+
+---
+
+## Troubleshooting
+
+### Server won't start
+
+**Error:** `DATABASE_URL not configured`
+- Make sure `.env` file exists with `DATABASE_URL`
+- Check database is running: `psql $DATABASE_URL -c "SELECT 1"`
+
+**Error:** `Address already in use`
+- Port 8080 is already taken
+- Change port: `WEB_PORT=8081`
+- Or kill existing process: `lsof -ti:8080 | xargs kill`
+
+### Can't access from other devices
+
+**Problem:** Server only accessible on localhost
+
+**Solution:** Change host to `0.0.0.0`:
+```env
+WEB_HOST=0.0.0.0
+```
+
+Then access via: `http://<your-ip>:8080`
+
+### CORS errors in browser
+
+**Problem:** Frontend at different origin can't access API
+
+**Solution:** Add origin to CORS whitelist:
+```env
+WEB_CORS_ORIGINS=["http://localhost:3000", "http://your-frontend.com"]
+```
+
+### Rate limit errors
+
+**Problem:** Getting 429 errors
+
+**Solution:** Increase rate limit:
+```env
+WEB_RATE_LIMIT=120  # Requests per minute
+```
+
+---
+
+## Architecture
+
+```
+Browser → FastAPI → ConversationGateway → Living AI → Database
+```
+
+**Intimacy Level:** HIGH (always)
+- Deeper reflection
+- Proactive follow-ups
+- Fact extraction enabled
+- Emotional naming encouraged
+
+---
+
+## Development Tips
+
+### Auto-reload on code changes
+
+```bash
+python3 run_web.py  # Already has reload=True
+```
+
+### Check logs
+
+```bash
+# Console logs show all requests
+# Look for:
+# → POST /api/chat
+# ← POST /api/chat [200] (1.23s)
+```
+
+### Test with different users
+
+Use different email addresses:
+```bash
+# User 1
+curl ... -H "Authorization: Bearer web:alice@example.com"
+
+# User 2
+curl ... -H "Authorization: Bearer web:bob@example.com"
+```
+
+Each gets separate conversations and relationships.
+
+---
+
+## Next Steps
+
+- Deploy to production server
+- Add HTTPS/TLS
+- Implement proper JWT authentication
+- Add WebSocket for real-time updates
+- Build richer UI (markdown, images)
+- Add account linking with Discord
+
+---
+
+**The Web platform is ready!** 🌐
+
+Visit http://localhost:8080 and start chatting.