https://github.com/readingbat/readingbat-core
ReadingBat Core
https://github.com/readingbat/readingbat-core
educational-software kotlin programming-challenges
Last synced: 16 days ago
JSON representation
ReadingBat Core
- Host: GitHub
- URL: https://github.com/readingbat/readingbat-core
- Owner: readingbat
- License: apache-2.0
- Created: 2020-04-22T19:28:51.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2026-05-04T06:19:59.000Z (16 days ago)
- Last Synced: 2026-05-04T06:26:02.770Z (16 days ago)
- Topics: educational-software, kotlin, programming-challenges
- Language: Kotlin
- Homepage: https://readingbat.github.io/readingbat-core/
- Size: 30.8 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
README
# ReadingBat Core
[](https://github.com/readingbat/readingbat-core/releases)
[](https://central.sonatype.com/artifact/com.readingbat/readingbat-core)
[](https://github.com/readingbat/readingbat-core/actions/workflows/test.yml)
[](https://codecov.io/gh/readingbat/readingbat-core)
[](https://kotlinlang.org/)
[](https://pinterest.github.io/ktlint/)
A Kotlin-based framework for creating interactive programming challenges and educational content, powering the
[ReadingBat](https://readingbat.com) platform for teaching Java, Kotlin, and Python programming concepts.
## 🚀 Features
- **Multi-Language Support**: Create challenges for Java, Kotlin, and Python
- **Interactive DSL**: Expressive domain-specific language for defining programming exercises
- **Web-Based Platform**: Built on Ktor with real-time WebSocket updates
- **User Management**: Complete authentication system with class/teacher support
- **Progress Tracking**: Detailed analytics and progress monitoring
- **Scalable Architecture**: Multi-server deployment ready with database persistence
## 🏗️ Architecture
ReadingBat Core is built using modern Kotlin technologies:
- **Web Framework**: Ktor 3.4.3 with CIO engine
- **Database**: PostgreSQL with Exposed ORM (`exposed-kotlin-datetime`) and HikariCP connection pooling
- **Authentication**: OAuth (GitHub, Google) with session management
- **Script Execution**: JSR-223 scripting engines for safe code evaluation
- **Build System**: Gradle 9.5 with Kotlin DSL, multi-module structure, and configuration cache enabled
- **Serialization**: kotlinx.serialization for JSON processing
- **Testing**: Kotest framework with Playwright for E2E testing
## 📁 Project Structure
```
readingbat-core/
├── readingbat-core/ # Main application module
│ ├── src/main/kotlin/
│ │ └── com/readingbat/
│ │ ├── dsl/ # Content DSL and challenge types
│ │ ├── pages/ # HTML page generation
│ │ ├── server/ # Core server infrastructure
│ │ ├── posts/ # Form handling
│ │ └── common/ # Shared utilities
│ └── src/main/resources/ # Configuration and static assets
├── readingbat-kotest/ # Testing utilities module
├── docs/ # Documentation
└── sql/ # Database migration scripts
```
## 🚦 Quick Start
### Prerequisites
- Java 17+
- Docker (for PostgreSQL)
### Development Setup
1. **Clone the repository**
```bash
git clone https://github.com/readingbat/readingbat-core.git
cd readingbat-core
```
2. **Start PostgreSQL with Docker**
```bash
mkdir -p $HOME/docker/volumes/postgres
docker run --rm --name pg-docker -e POSTGRES_PASSWORD=docker -d -p 5432:5432 \
-v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres
```
3. **Setup database**
```bash
make dbreset # or ./gradlew flywayClean flywayMigrate
```
4. **Build and run**
```bash
make build # or ./gradlew build -xtest
make run # or ./gradlew run
```
5. **Open browser**
Navigate to `http://localhost:8080`
### Environment Configuration
Create application configuration file or set environment variables:
```bash
# Database
export DBMS_URL="jdbc:pgsql://localhost:5432/readingbat"
export DBMS_USERNAME="postgres"
export DBMS_PASSWORD="docker"
# Optional: OAuth (auto-configured when credentials are present)
export GITHUB_OAUTH="your_github_token"
export IPGEOLOCATION_KEY="your_geo_key"
```
## 🛠️ Development Commands
### Build & Test
```bash
make build # Build project (skip tests)
make tests # Run unit tests
make lint # Lint Kotlin code
make coverage # Generate Kover HTML coverage report
make coverage-verify # Enforce coverage thresholds via Kover
```
### Database Operations
```bash
make dbmigrate # Run database migrations
make dbreset # Clean and migrate database
make dbinfo # Show migration status
```
### Running & Deployment
```bash
make run # Run development server
make uberjar # Create standalone JAR
make uber # Build and run JAR
```
### Testing
```bash
make tests # Run all tests
```
## 🎯 Creating Content
ReadingBat uses a powerful DSL for creating programming challenges:
```kotlin
readingBatContent {
java {
group("Warm-Up") {
packageName = "com.readingbat.java.warmup"
challenge("simple_addition") {
returnType = IntType
description = "Return the sum of two integers"
function("addTwo(int a, int b)") {
returnType = IntType
addToCorrectAnswers(1 + 2, 3 + 4, 5 + 6)
}
}
}
}
}
```
See the [template repository](https://github.com/readingbat/readingbat-template) for complete examples.
## 🏗️ Deployment
### Local Development
```bash
# Using Docker Compose
docker-compose up -d postgres
make run
```
### Production Deployment
ReadingBat Core supports multiple deployment targets:
- **Heroku**: Uses `Procfile` and Heroku Postgres
- **Google Cloud Run**: Cloud SQL integration with connection pooling
- **Digital Ocean**: App Platform with managed PostgreSQL
- **Docker**: Containerized deployment with environment configuration
Required environment variables for production:
- `DBMS_URL`, `DBMS_USERNAME`, `DBMS_PASSWORD`
- `AGENT_ENABLED=true` (for monitoring)
- `RESEND_API_KEY` (for email notifications)
## 🧪 Testing
### Unit Tests
```bash
./gradlew test # Run Kotest unit tests
```
### End-to-End Tests
```bash
# Playwright-based browser tests run as part of the Kotest suite
./gradlew :readingbat-core:test
```
## 📊 Monitoring & Metrics
ReadingBat Core includes comprehensive monitoring:
- **Prometheus Metrics**: Application metrics and JVM stats
- **Request Tracking**: Detailed request logging and timing
- **User Analytics**: Challenge completion and progress tracking
- **Database Monitoring**: Connection pool and query performance
## 📚 Related Projects
- **[ReadingBat Template](https://github.com/readingbat/readingbat-template)**: Template for creating custom content
## 📄 License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
---
**ReadingBat Core** - Making programming education interactive and engaging through hands-on challenges.