{"id":48470367,"url":"https://github.com/readingbat/readingbat-core","last_synced_at":"2026-05-04T08:05:19.220Z","repository":{"id":37535730,"uuid":"257999905","full_name":"readingbat/readingbat-core","owner":"readingbat","description":"ReadingBat Core","archived":false,"fork":false,"pushed_at":"2026-05-04T06:19:59.000Z","size":32269,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-04T06:26:02.770Z","etag":null,"topics":["educational-software","kotlin","programming-challenges"],"latest_commit_sha":null,"homepage":"https://readingbat.github.io/readingbat-core/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/readingbat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-04-22T19:28:51.000Z","updated_at":"2026-05-04T04:53:12.000Z","dependencies_parsed_at":"2024-01-11T09:13:51.983Z","dependency_job_id":"379d6bc8-1a7b-4a63-9505-7886bdd73216","html_url":"https://github.com/readingbat/readingbat-core","commit_stats":null,"previous_names":[],"tags_count":96,"template":false,"template_full_name":null,"purl":"pkg:github/readingbat/readingbat-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readingbat%2Freadingbat-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readingbat%2Freadingbat-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readingbat%2Freadingbat-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readingbat%2Freadingbat-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readingbat","download_url":"https://codeload.github.com/readingbat/readingbat-core/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readingbat%2Freadingbat-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32599416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["educational-software","kotlin","programming-challenges"],"created_at":"2026-04-07T06:03:31.020Z","updated_at":"2026-05-04T08:05:19.214Z","avatar_url":"https://github.com/readingbat.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReadingBat Core\n\n[![GitHub release](https://img.shields.io/github/v/release/readingbat/readingbat-core?logo=github)](https://github.com/readingbat/readingbat-core/releases)\n[![Maven Central](https://img.shields.io/maven-central/v/com.readingbat/readingbat-core?logo=apachemaven)](https://central.sonatype.com/artifact/com.readingbat/readingbat-core)\n[![Tests](https://github.com/readingbat/readingbat-core/actions/workflows/test.yml/badge.svg)](https://github.com/readingbat/readingbat-core/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/readingbat/readingbat-core/branch/master/graph/badge.svg)](https://codecov.io/gh/readingbat/readingbat-core)\n[![Kotlin](https://img.shields.io/badge/%20language-Kotlin-red.svg)](https://kotlinlang.org/)\n[![ktlint](https://img.shields.io/badge/ktlint%20code--style-%E2%9D%A4-FF4081)](https://pinterest.github.io/ktlint/)\n\nA Kotlin-based framework for creating interactive programming challenges and educational content, powering the\n[ReadingBat](https://readingbat.com) platform for teaching Java, Kotlin, and Python programming concepts.\n\n## 🚀 Features\n\n- **Multi-Language Support**: Create challenges for Java, Kotlin, and Python\n- **Interactive DSL**: Expressive domain-specific language for defining programming exercises\n- **Web-Based Platform**: Built on Ktor with real-time WebSocket updates\n- **User Management**: Complete authentication system with class/teacher support\n- **Progress Tracking**: Detailed analytics and progress monitoring\n- **Scalable Architecture**: Multi-server deployment ready with database persistence\n\n## 🏗️ Architecture\n\nReadingBat Core is built using modern Kotlin technologies:\n\n- **Web Framework**: Ktor 3.4.3 with CIO engine\n- **Database**: PostgreSQL with Exposed ORM (`exposed-kotlin-datetime`) and HikariCP connection pooling\n- **Authentication**: OAuth (GitHub, Google) with session management\n- **Script Execution**: JSR-223 scripting engines for safe code evaluation\n- **Build System**: Gradle 9.5 with Kotlin DSL, multi-module structure, and configuration cache enabled\n- **Serialization**: kotlinx.serialization for JSON processing\n- **Testing**: Kotest framework with Playwright for E2E testing\n\n## 📁 Project Structure\n\n```\nreadingbat-core/\n├── readingbat-core/          # Main application module\n│   ├── src/main/kotlin/\n│   │   └── com/readingbat/\n│   │       ├── dsl/          # Content DSL and challenge types\n│   │       ├── pages/        # HTML page generation\n│   │       ├── server/       # Core server infrastructure\n│   │       ├── posts/        # Form handling\n│   │       └── common/       # Shared utilities\n│   └── src/main/resources/   # Configuration and static assets\n├── readingbat-kotest/        # Testing utilities module\n├── docs/                     # Documentation\n└── sql/                      # Database migration scripts\n```\n\n## 🚦 Quick Start\n\n### Prerequisites\n\n- Java 17+\n- Docker (for PostgreSQL)\n\n### Development Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/readingbat/readingbat-core.git\n   cd readingbat-core\n   ```\n\n2. **Start PostgreSQL with Docker**\n   ```bash\n   mkdir -p $HOME/docker/volumes/postgres\n   docker run --rm --name pg-docker -e POSTGRES_PASSWORD=docker -d -p 5432:5432 \\\n     -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres\n   ```\n\n3. **Setup database**\n   ```bash\n   make dbreset  # or ./gradlew flywayClean flywayMigrate\n   ```\n\n4. **Build and run**\n   ```bash\n   make build    # or ./gradlew build -xtest\n   make run      # or ./gradlew run\n   ```\n\n5. **Open browser**\n   Navigate to `http://localhost:8080`\n\n### Environment Configuration\n\nCreate application configuration file or set environment variables:\n\n```bash\n# Database\nexport DBMS_URL=\"jdbc:pgsql://localhost:5432/readingbat\"\nexport DBMS_USERNAME=\"postgres\"\nexport DBMS_PASSWORD=\"docker\"\n\n# Optional: OAuth (auto-configured when credentials are present)\nexport GITHUB_OAUTH=\"your_github_token\"\nexport IPGEOLOCATION_KEY=\"your_geo_key\"\n```\n\n## 🛠️ Development Commands\n\n### Build \u0026 Test\n\n```bash\nmake build              # Build project (skip tests)\nmake tests              # Run unit tests\nmake lint               # Lint Kotlin code\nmake coverage           # Generate Kover HTML coverage report\nmake coverage-verify    # Enforce coverage thresholds via Kover\n```\n\n### Database Operations\n\n```bash\nmake dbmigrate      # Run database migrations\nmake dbreset        # Clean and migrate database\nmake dbinfo         # Show migration status\n```\n\n### Running \u0026 Deployment\n\n```bash\nmake run            # Run development server\nmake uberjar        # Create standalone JAR\nmake uber           # Build and run JAR\n```\n\n### Testing\n\n```bash\nmake tests          # Run all tests\n```\n\n## 🎯 Creating Content\n\nReadingBat uses a powerful DSL for creating programming challenges:\n\n```kotlin\nreadingBatContent {\n  java {\n    group(\"Warm-Up\") {\n      packageName = \"com.readingbat.java.warmup\"\n\n      challenge(\"simple_addition\") {\n        returnType = IntType\n        description = \"Return the sum of two integers\"\n\n        function(\"addTwo(int a, int b)\") {\n          returnType = IntType\n          addToCorrectAnswers(1 + 2, 3 + 4, 5 + 6)\n        }\n      }\n    }\n  }\n}\n```\n\nSee the [template repository](https://github.com/readingbat/readingbat-template) for complete examples.\n\n## 🏗️ Deployment\n\n### Local Development\n\n```bash\n# Using Docker Compose\ndocker-compose up -d postgres\nmake run\n```\n\n### Production Deployment\n\nReadingBat Core supports multiple deployment targets:\n\n- **Heroku**: Uses `Procfile` and Heroku Postgres\n- **Google Cloud Run**: Cloud SQL integration with connection pooling\n- **Digital Ocean**: App Platform with managed PostgreSQL\n- **Docker**: Containerized deployment with environment configuration\n\nRequired environment variables for production:\n\n- `DBMS_URL`, `DBMS_USERNAME`, `DBMS_PASSWORD`\n- `AGENT_ENABLED=true` (for monitoring)\n- `RESEND_API_KEY` (for email notifications)\n\n## 🧪 Testing\n\n### Unit Tests\n\n```bash\n./gradlew test  # Run Kotest unit tests\n```\n\n### End-to-End Tests\n\n```bash\n# Playwright-based browser tests run as part of the Kotest suite\n./gradlew :readingbat-core:test\n```\n\n## 📊 Monitoring \u0026 Metrics\n\nReadingBat Core includes comprehensive monitoring:\n\n- **Prometheus Metrics**: Application metrics and JVM stats\n- **Request Tracking**: Detailed request logging and timing\n- **User Analytics**: Challenge completion and progress tracking\n- **Database Monitoring**: Connection pool and query performance\n\n## 📚 Related Projects\n\n- **[ReadingBat Template](https://github.com/readingbat/readingbat-template)**: Template for creating custom content\n\n## 📄 License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n\n---\n\n**ReadingBat Core** - Making programming education interactive and engaging through hands-on challenges.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadingbat%2Freadingbat-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadingbat%2Freadingbat-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadingbat%2Freadingbat-core/lists"}