CritiqueQuest

Important

CritiqueQuest has been retired and this repository is archived. Development has moved to its successor, Playable Lessons (source on GitHub). The documentation site and bring-your-own-key browser demo remain online as-is, but there will be no further releases, fixes, or support for CritiqueQuest.

Every case, a new discovery

Desktop application for generating AI-powered educational case studies with support for OpenAI, Anthropic, Google Gemini, and local Ollama models.

🎯 Overview

CritiqueQuest empowers educators and students to create high-quality, AI-generated case studies for educational purposes. Whether you're a lecturer developing engaging scenarios for your students or a student practicing critical thinking skills, CritiqueQuest transforms learning concepts into compelling case studies in minutes.

With support for both cloud-based AI services and local models through Ollama, it offers flexibility between convenience and complete privacy.

✨ Key Features

• 🤖 Multi-Provider AI Support - OpenAI GPT-4, Google Gemini, Anthropic Claude, and Ollama (local)
• 🔒 Privacy-First Option - Run AI models locally with Ollama for complete data privacy
• 📚 Local Content Library - Organize, search, and manage your case studies
• 🎮 Practice Mode - Interactive self-assessment with timers and note-taking
• 📄 Multiple Export Formats - PDF, Word, HTML, and plain text
• 🎨 Intuitive Interface - Material-UI components with professional design
• 💾 Offline-First - Works without internet (with local AI models)

👥 Perfect For

📚 Educators & Lecturers

• Create engaging case studies for any subject area
• Generate scenarios with varying complexity levels
• Export content for course materials and assignments
• Build comprehensive case study libraries

🎓 Students & Learners

• Practice critical thinking with AI-generated scenarios
• Self-assess understanding through guided practice mode
• Create study materials for exam preparation
• Develop analytical skills across different domains

🚀 Quick Start

Prerequisites

• Node.js 22.12+ and npm (Node 24 recommended; Electron dev and Vite 8 both require ≥22.12)
• (Optional) Ollama for local AI models

Installation

# Clone the repository
git clone https://github.com/michael-borck/critiquequest.git
cd critiquequest

# Install dependencies
npm install

# Start development mode
npm run dev

First-Time Setup

1. Launch the application
2. Navigate to Settings → AI Configuration
3. Choose your AI provider:
   • Cloud AI: Add API key for OpenAI/Google/Anthropic
   • Local AI: Install Ollama and pull a model (e.g., ollama pull llama2)
4. Start generating case studies!

🐳 Self-Hosted Web App (Docker)

Prefer a multi-user web app you host yourself? CritiqueQuest also ships a self-hosted server (Fastify + SQLite, per-user accounts) from the same codebase:

cp .env.example .env   # set CRITIQUEQUEST_SECRET (openssl rand -hex 32)
docker compose up -d --build
# open http://localhost:8787 and create the first account

See SELF_HOSTING.md for configuration, system-wide AI keys, and the optional bundled Ollama service.

📖 Usage

Generating Case Studies

1. Click Generate in the sidebar
2. Configure your case study:
   • Domain: Business, Technology, Healthcare, Education, etc.
   • Complexity: Beginner, Intermediate, or Advanced
   • Scenario Type: Problem-solving, Decision-making, Ethical dilemmas
   • Context: Describe the scenario setting
3. Click Generate Case Study
4. Review and save the generated content

Managing Your Library

• Search across all case studies
• Filter by domain, complexity, or favorites
• Tag content for better organization
• Export in multiple formats for sharing or printing

Practice Mode

1. Select a case study from your library
2. Click Practice to start self-assessment
3. Work through questions step-by-step
4. Compare with AI-generated model answers
5. Track your progress with session notes

🔧 Configuration

Using Cloud AI (OpenAI, etc.)

// Settings → AI Configuration
{
  "provider": "openai",
  "apiKey": "your-api-key-here",
  "model": "gpt-4"
}

Using Local AI (Ollama)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

# Start Ollama service
ollama serve

# Configure in CritiqueQuest Settings

See OLLAMA_SETUP.md for detailed instructions.

🏗️ Architecture

critiquequest/
├── src/
│   ├── main/              # Electron main process (desktop only)
│   │   ├── main.ts        # App lifecycle + secure ipcMain.handle handlers
│   │   ├── preload.ts     # contextBridge → window.electronAPI
│   │   └── secret-box.ts  # ElectronSecretBox (OS keychain via safeStorage)
│   ├── renderer/          # React + MUI + Zustand UI (transport-agnostic)
│   │   ├── main.tsx       # Picks preload (desktop) or httpApi (web)
│   │   ├── api/httpApi.ts # HTTP transport for the web build
│   │   ├── components/    # UI components
│   │   ├── store/         # Zustand state
│   │   └── contexts/      # Theme / settings
│   ├── core/              # Transport-agnostic core shared by both builds
│   │   ├── database.ts    # DatabaseManager — desktop Store (node-json-db)
│   │   ├── ai-service.ts  # Multi-provider AI via a switch statement
│   │   ├── file-service.ts# Export / import
│   │   ├── store.ts       # Store interface (port)
│   │   ├── secret-box.ts  # SecretBox interface (port)
│   │   └── url-guard.ts   # assertPublicUrl SSRF guard
│   ├── server/            # Self-hosted Fastify + SQLite multi-user server
│   │   ├── server.ts      # Fastify app, auth routes, rate limiting
│   │   ├── rpc.ts         # /api/rpc dispatch over RPC_METHODS
│   │   ├── sqlite-store.ts# SqliteStore — server Store (per-user isolation)
│   │   ├── db.ts          # better-sqlite3, WAL mode
│   │   ├── auth.ts        # scrypt password hashing + session tokens
│   │   ├── index.ts       # Server entrypoint
│   │   └── secret-box.ts  # EnvSecretBox (AES-256-GCM)
│   └── shared/            # types, validation, textAnalysis, html, conceptDatabase
├── dist/                  # Build output
└── release/               # Distribution packages

CritiqueQuest is one codebase, two deployments: an Electron desktop app and an optional self-hosted multi-user web server. Both share the transport-agnostic src/core (data, AI, files, ports) and src/shared (types, validation). The desktop persists to a local JSON file (node-json-db); the server persists to SQLite (better-sqlite3, WAL) with per-user row isolation. To run the server, see SELF_HOSTING.md.

🛠️ Development

Available Scripts

npm run dev          # Start development mode
npm run build        # Build for production
npm run dist         # Create distribution packages
npm run lint         # Run ESLint
npm run typecheck    # TypeScript type checking

Technology Stack

• Frontend: React 18 + TypeScript + Material-UI
• Backend: Electron main process (desktop) / Fastify (self-hosted server)
• State Management: Zustand
• Database: JSON (node-json-db) on desktop; SQLite (better-sqlite3, WAL) on the self-hosted server
• Build Tools: Vite + electron-builder

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Maintain type safety throughout
• Write clear commit messages
• Update documentation as needed
• Test with both cloud and local AI providers

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Electron - Desktop framework
• React - UI library
• Material-UI - Component library
• Ollama - Local AI model support
• OpenAI - GPT models
• All contributors and users of CritiqueQuest

📞 Support

• Documentation: Check the /docs folder
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Transform learning concepts into engaging case studies in minutes! 🚀