KarlBot

The application is available online at karlbot.dev.

KarlBot is a development environment for an educational programming language Karel. Karel's original author is Professor Richard Pattis, but since then many more or less similar variants have been created and this is one of them. It has the following features:

• Syntax highlighting
• Code completion
• Automatic indentation
• Error checking
• Advanced town editor
• Running Karel's program
• Saving projects on the server
• Saving projects locally
• Sharing projects via URL
• Debugger with stepping, breakpoints and call stack view
• Automatically evaluated challenges
• Mobile phones support

Developer Guide

Project Overview

The application uses a three-tier architecture. It is divided into client, server, and database. The main used technologies are these:

• Client: TypeScript, Angular
  • User interface: Angular Material
  • Code editor: CodeMirror
  • Markdown renderer: markdown-it
  • Tests: Cypress, Jasmine
  • Documentation: Compodoc, TypeDoc
• Server: C#, ASP.NET Core
  • ORM: Entity Framework Core
  • Running JavaScript (challenge evaluation): ClearScript
  • Tests: NUnit, Moq
  • Documentation: Swagger UI, docfx
• Database: Microsoft SQL Server

For user authentication is used Firebase Authentication.

...And many others.

Directory structure

• /.github: CI/CD pipeline.
• /client: Client implementation.
• /server: Server implementation.
• /firebase-emulator: Emulator of the Firebase platform.

Development configuration files

• Client: /client/projects/application/src/environments/environment.development.ts
• Server: /server/KarlBot/appsettings.Development.json
  • Database integration tests: /server/Infrastructure.Tests/appsettings.json
• Firebase emulator: /firebase-emulator/firebase.json

Git branches

• develop: The actual development is taking place here.
• master: Contains the latest release version. When a new version of the application is ready, a merge from develop to master is performed and the CI/CD pipeline automatically deploys it to karlbot.dev.

How to run it

Prerequisites:

• Windows (or Linux – not tested, but it should work)
• Git installed
• .NET 7 SDK installed
• SQL Server Express LocalDB (or another SQL Server distribution) installed and running
• Node.js 18 installed
• Firebase CLI installed (npm install -g firebase-tools)
• Angular CLI installed (npm install -g @angular/cli)

If you want to run the project locally, please follow these steps:

Clone the repository:

git clone https://github.com/vosa53/karlbot.git
cd karlbot

Start the Firebase Authentication emulator:

cd firebase-emulator
firebase emulators:start --import data --export-on-exit data --project demo-test

Alternative: Or just use /firebase-emulator/start-firebase-emulator.bat in the case of the Windows operating system.

Build the client:

cd client
npm install

cd projects/karel
npm install
ng build karel
npm run build

cd ../karel-evalution
npm install
ng build karel-evaluation
npm run build

Start the server:

cd server/KarlBot
dotnet run --launch-profile "https"

Alternative: On Windows, you can use Visual Studio. Open /server/KarlBot.sln and run project KarlBot with https launch profile.

For Linux users: SQL Server Express LocalDB does not support Linux, you have to use a different SQL Server distribution and specify its connection string in the server configuration file.

It should run at https://localhost:7105. Its REST API documentation in Swagger UI is then available at https://localhost:7105/swagger.

Start the client:

cd client
ng serve --open

It also opens a web browser with the application GUI.

How to get administrator permissions

Challenge editation is available only for administrators.

1. Sign in to the application.
2. Go to the database and find your user ID (AspNetUsers table).
3. Run these SQL commands:

INSERT INTO AspNetRoles(Id, Name) VALUES('f21cd4b8-94b0-4516-9429-311da93b5a2d', 'Admin')
INSERT INTO AspNetUserRoles(UserId, RoleId) VALUES('<Your ID>', 'f21cd4b8-94b0-4516-9429-311da93b5a2d')

How to run tests

Prerequisites:

• Previous step

Server:

cd server
dotnet test

For Linux users: Same problem with SQL Server as in the run section. Please specify your connection string in the server integration tests configuration file.

Client:

cd client
npm run test
npm run lint

End-to-end:

1. Launch the client and server with an environment variable IsEndToEndTest set to true (that clears the database and prepares test data).

2. Run:

cd client
npx cypress open

3. Wait for Cypress UI to open.
4. Click on E2E Testing.
5. Select Chrome browser.
6. Click on Start E2E Testing in Chrome.
7. Open create-project-challenge-and-submit-it.cy.ts test spec.

Alternative: If you don't need the UI then simply use npx cypress run (client and server running is still needed).

How to generate the documentation

Prerequisites:

• Previous steps
• docfx installed (dotnet tool update -g docfx)

Server:

cd server
docfx docfx_project/docfx.json

Documentation is generated in /server/docfx_project/_site. It has to be served by some (local) web server (opening index.html directly in the browser won't work). For example, this web server can be used.

Client:

cd client
npm run documentation

Documentation is generated in /client/docs. Every project has its own folder.