--- title: MemPrepMate emoji: πŸ“š colorFrom: green colorTo: purple sdk: docker pinned: false short_description: AI Agent with MemMachine to prepare for conversations app_port: 7860 hf_oauth: true hf_oauth_scopes: - email --- # ⚠️ CRITICAL: Required Environment Variables for OAuth **OAuth will NOT work without these variables set in Space Settings β†’ Variables:** | Variable | Value | Required For | |----------|-------|-------------| | `SESSION_COOKIE_SECURE` | `true` | HTTPS cookie security | | `SESSION_COOKIE_SAMESITE` | `None` | Cross-site OAuth redirects | | `PREFERRED_URL_SCHEME` | `https` | Correct OAuth URLs | | `SECRET_KEY` | *random 32-byte hex* | Session encryption | **Generate SECRET_KEY:** `openssl rand -hex 32` **Without these, you'll see:** - ❌ "mismatching_state: CSRF Warning!" - ❌ Browser blocks session cookie (missing Secure/SameSite=None) - ❌ Empty session on OAuth callback - ❌ Infinite redirect loop **After setting variables:** 1. Space will rebuild automatically 2. Check logs for: `[CONFIG] SESSION_COOKIE_SECURE=True` 3. Cookie should show: `Secure; SameSite=None` --- # PrepMate Webapp - Profile and Contact Management UI# PrepMate Webapp Flask-based web application for managing user profiles and contact sessions with HuggingFace OAuth authentication.Modern web application for PrepMate built with Svelte, SvelteKit, and Bootstrap 5. ## Quick Start## Technology Stack ### Prerequisites- **Framework**: Svelte 4.2+ with SvelteKit 2.0+ - **Language**: TypeScript 5.3+ (strict mode) - Python 3.11+- **Styling**: Bootstrap 5.3 + Bootstrap Icons 1.11 - HuggingFace OAuth app credentials- **Build Tool**: Vite 5.0+ - Backend API running (Go server)- **Testing**: Vitest (unit) + Playwright (e2e) - **HTTP Client**: Native Fetch API ### Local Development ## Prerequisites 1. **Install dependencies:** ```bash- Node.js 20.x or later pip install -r requirements.txt- npm 10.x or later ```- Docker (for backend services) 2. **Configure environment:**## Quick Start ```bash cp .env.example .env### 1. Install Dependencies # Edit .env with your HF OAuth credentials ``````bash npm install 3. **Initialize database:**``` ```bash python -c "from src.services.storage_service import init_db; init_db()"### 2. Start Backend Services ``` From the repository root: 4. **Run development server:** ```bash```bash export FLASK_APP=src.app:appdocker compose up -d api postgres memory-backend export FLASK_ENV=development``` flask run --port=5000 ```### 3. Start Development Server Access at: http://localhost:5000```bash npm run dev ### Docker Development``` ```bashThe webapp will be available at `http://localhost:5173` # From repository root docker-compose up webapp## Development ``` ### Available Scripts Access at: http://localhost:5000 - `npm run dev` - Start development server with hot reload ## Project Structure- `npm run build` - Build for production - `npm run preview` - Preview production build locally ```- `npm test` - Run unit tests in watch mode webapp/- `npm run test:unit` - Run unit tests once β”œβ”€β”€ src/- `npm run test:e2e` - Run end-to-end tests β”‚ β”œβ”€β”€ app.py # Flask application- `npm run test:e2e:ui` - Run e2e tests with UI β”‚ β”œβ”€β”€ models/ # Data models- `npm run check` - Type-check TypeScript β”‚ β”œβ”€β”€ services/ # Business logic- `npm run lint` - Lint code with ESLint β”‚ β”œβ”€β”€ routes/ # HTTP routes- `npm run format` - Format code with Prettier β”‚ β”œβ”€β”€ templates/ # Jinja2 templates β”‚ └── static/ # CSS/JS assets### Project Structure β”œβ”€β”€ tests/ # Unit and integration tests β”œβ”€β”€ data/ # SQLite database``` β”œβ”€β”€ migrations/ # Database migrationswebapp/ └── requirements.txt # Python dependenciesβ”œβ”€β”€ src/ ```β”‚ β”œβ”€β”€ lib/ β”‚ β”‚ β”œβ”€β”€ components/ # Svelte UI components ## Featuresβ”‚ β”‚ β”œβ”€β”€ services/ # Business logic & API clients β”‚ β”‚ β”œβ”€β”€ stores/ # Svelte stores (state management) - **User Profile Management**: Maintain personal facts via HuggingFace OAuthβ”‚ β”‚ β”œβ”€β”€ types/ # TypeScript type definitions - **Contact Sessions**: Create isolated sessions for different contactsβ”‚ β”‚ └── utils/ # Helper functions - **Fact Management**: Add/edit facts with 2000 character limitβ”‚ β”œβ”€β”€ routes/ # SvelteKit pages (file-based routing) - **Message Exchange**: Send/receive messages with backend LLM integrationβ”‚ └── app.html # HTML template - **Contact Navigation**: Search and sort contacts by recent activityβ”œβ”€β”€ static/ # Static assets (favicon, robots.txt) β”œβ”€β”€ tests/ ## Testingβ”‚ β”œβ”€β”€ unit/ # Vitest unit tests β”‚ └── e2e/ # Playwright e2e tests ```bash└── package.json # Unit tests``` pytest tests/unit/ -v ### Environment Variables # Integration tests pytest tests/integration/ -vCreate `.env.development` for local development: # Coverage report```bash pytest --cov=src --cov-report=html# API Configuration ```VITE_API_URL=http://localhost:4004 VITE_API_TIMEOUT=30000 ## Configuration # Authentication See `.env.example` for all available environment variables.VITE_ENABLE_MOCK_AUTH=true VITE_MOCK_USER_ID=testuser Key settings:VITE_MOCK_USERNAME=Test User - `HF_CLIENT_ID`: HuggingFace OAuth app client IDVITE_MOCK_EMAIL=testuser@example.com - `HF_CLIENT_SECRET`: HuggingFace OAuth app secret - `BACKEND_API_URL`: Backend API base URL (default: http://api:4004/v1)# Feature Flags - `SECRET_KEY`: Flask session secret (generate with `python -c "import secrets; print(secrets.token_hex(32))"`)VITE_ENABLE_COMPARISON=true VITE_SESSION_LIMIT=20 ## Troubleshooting``` See [quickstart.md](../specs/012-profile-contact-ui/quickstart.md) for detailed setup instructions and troubleshooting.## Testing ### Unit Tests ```bash # Run all unit tests npm test # Run specific test file npm test -- src/lib/services/api.test.ts # Run with coverage npm test -- --coverage ``` ### End-to-End Tests ```bash # Run all e2e tests npm run test:e2e # Run with UI npm run test:e2e:ui # Run specific browser npm run test:e2e -- --project=chromium ``` ## Building for Production ```bash # Create optimized production build npm run build # Preview production build locally npm run preview ``` The build output will be in the `build/` directory. ## Docker ### Build and Run ```bash # Build Docker image docker build -t prepmate-webapp . # Run container docker run -p 5173:80 prepmate-webapp ``` ### Docker Compose From the repository root: ```bash # Start all services including webapp docker compose up -d # View logs docker compose logs -f webapp # Rebuild after changes docker compose build webapp && docker compose up -d webapp ``` The webapp will be available at `http://localhost:5173` ## Architecture ### State Management The webapp uses Svelte stores for reactive state management: - **Auth Store** (`stores/auth.ts`): User authentication state - **Session Store** (`stores/session.ts`): Active session and sessions list - **UI Store** (`stores/ui.ts`): UI state (sidebar visibility, loading, errors) ### API Integration The webapp communicates with the Go API backend using a centralized API client (`services/api.ts`) that: - Wraps native Fetch API - Handles authentication (Bearer token + X-User-ID headers) - Implements retry logic and timeout handling - Provides type-safe methods for all endpoints ### Routing SvelteKit provides file-based routing: - `/` - Home page (session list) - `/login` - Login page (OAuth or mock) - `/session/[id]` - Session detail (chat interface) - `/auth/callback` - OAuth callback handler ## Contributing ### Code Style - TypeScript strict mode enabled - ESLint for linting - Prettier for formatting - Follow existing patterns in components and services ### Testing Requirements - Unit tests for all services and stores (>80% coverage goal) - Unit tests for complex components - E2e tests for critical user flows - All tests must pass before committing ### Pull Request Process 1. Create feature branch from `main` 2. Implement changes with tests 3. Run `npm run check` and `npm run lint` 4. Run all tests (`npm test` and `npm run test:e2e`) 5. Update documentation if needed 6. Submit PR with clear description ## Troubleshooting ### Port Already in Use ```bash # Find process using port 5173 lsof -i :5173 # Kill process kill -9 # Or use different port npm run dev -- --port 5174 ``` ### Node Modules Issues ```bash # Clear and reinstall rm -rf node_modules package-lock.json npm install ``` ### API Connection Errors ```bash # Verify API is running curl http://localhost:4004/health # Check docker logs docker compose logs api # Restart API docker compose restart api ``` ### Build Errors ```bash # Clear caches rm -rf .svelte-kit node_modules/.vite # Rebuild npm run build ``` ## Performance ### Bundle Size Target: <500KB gzipped Check bundle size after build: ```bash npm run build ls -lh build/ ``` ### Lighthouse Scores Target: >90 performance score Run Lighthouse audit in Chrome DevTools or: ```bash npm run build npm run preview # Then run Lighthouse on http://localhost:5173 ``` ## Security - All user inputs are validated and sanitized - XSS protection via proper escaping - CSRF protection for state-changing operations - HTTPS enforced in production - Authentication tokens stored securely - Dependencies audited regularly (`npm audit`) ## License See repository root LICENSE file. ## Support For issues and questions, see the main repository README.