Spaces:
Sleeping
Sleeping
| 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: | |
| # ⚠️ 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 <PID> | |
| # 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. | |