README.md

metadata

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:

   
   pip install -r requirements.txt- npm 10.x or later
   
   ```- Docker (for backend services)
   
   

2. Configure environment:## Quick Start

   
   cp .env.example .env### 1. Install Dependencies
   
   # Edit .env with your HF OAuth credentials
   
   ``````bash
   

npm install

3. Initialize database:```

   
   python -c "from src.services.storage_service import init_db; init_db()"### 2. Start Backend Services
   

From the repository root:

4. Run development server:

   bashbash

   export FLASK_APP=src.app:appdocker compose up -d api postgres memory-backend

   export FLASK_ENV=development```

   flask run --port=5000

   
   
   
   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 [email protected]

- `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

# 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

# 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

# Build Docker image
docker build -t prepmate-webapp .

# Run container
docker run -p 5173:80 prepmate-webapp

Docker Compose

From the repository root:

# 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

# 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

# Clear and reinstall
rm -rf node_modules package-lock.json
npm install

API Connection Errors

# Verify API is running
curl http://localhost:4004/health

# Check docker logs
docker compose logs api

# Restart API
docker compose restart api

Build Errors

# Clear caches
rm -rf .svelte-kit node_modules/.vite

# Rebuild
npm run build

Performance

Bundle Size

Target: <500KB gzipped

Check bundle size after build:

npm run build
ls -lh build/

Lighthouse Scores

Target: >90 performance score

Run Lighthouse audit in Chrome DevTools or:

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.