Code organization#

The code is organized as a monolith that combines different sub-projects and languages.

Todo

Various features should perhaps be organized following a plugin architecture to increase flexibility and customizability. It also contains global CSS rules.

Directory structure#

Path

Description

build/

Directory to help build the software

ci/

GitLab CI configuration, e.g. for building the desktop app

electron/

Main and preload process of the desktop app

public/

Public assets

scripts/

Helper scripts for the setup and the build (Python environment, Pyodide download, …)

src/

Actual source code

tests/

Automated test suite (see Testing)

ChangeLog.md

Changes of every released version

index.html

Entry point into the website (WebTigerPython)

indexWEP.html

Entry point of WebEduPy

forge.config.ts

Electron Forge configuration of the desktop app

nginx.conf

Web server configuration

playwright.config.ts

Playwright configuration

README.md

-

requirements.txt

Python requirements

tsconfig.json, tsconfig.node.json

TypeScript configuration

vite.config.ts

Vite build tool configuration

vite.main.config.ts, vite.preload.config.ts

Vite configuration of the desktop app

public/assets/ directory#

This directory contains various assets required by the web application. The img folder provides logos, project icons, and various turtle icons. The jython_assets folder contains the sprites and sounds known from TigerJython (e.g. sprites/pony_1.gif), which can be used e.g. in GameGrid and GPanel. The roboticsSimulator folder holds graphics for robotics simulations, while the sprites folder contains SVG icons for UI elements.

assets/
├── img/
│   └── turtle-icons/
│
├── jython_assets/
│   ├── sprites/
│   └── wav/
│
├── roboticsSimulator/
│
└── sprites/

src/auth/ directory#

This directory contains the complete OAuth login flow for the application. It centralizes provider configuration, authentication state handling, callback processing, and shared utility helpers.

auth/
├── components/
│   └── OAuthCallback.vue   Handles OAuth redirect callback
├── index.ts                Public auth module exports
├── oauthConfig.ts          Provider manager configuration
├── oauthEnvConfig.ts       Environment-based OAuth settings
├── oauthManager.ts         Core authentication lifecycle logic
├── oauthStore.ts           Reactive Pinia auth state
├── oauthTypes.ts           Shared OAuth type definitions
├── oauthUtils.ts           Storage and callback helpers
└── README.md               OAuth module documentation guide

src/database/ directory#

This folder contains all logic related to database handling. It provides helper functions, type definitions, and adapters for working with databases.

database/
├── databaseInfoFetchHelper.ts
├── handleDatabase.ts
├── handleSqlite.ts
└── sqliteTypes.ts

src/devices/ directory#

Contains device modules with logic and files for supported hardware such as micro:bit, Calliope mini, Oxocard, Root Robot, xBot and ESP32 (see Robotics).

devices/
├── calliope/
│   ...
│   └── calliope.ts
├── calliope3/
│   ...
│   └── calliope3.ts
├── esp32/
│   └── esp32.ts                ESP32 (experimental), based on microPythonSerial
├── microbit/
│   ...
│   ├── microbit.ts
│   └── robotContext.py         RobotContext for the robotics simulator
├── microPythonSerial/
│   └── microPythonSerial.ts    Base class for MicroPython boards over Web Serial
├── oxocard/
│   ...
│   └── oxocard.ts
├── rootRobot/
│   └── rootRobot.ts            Root Robot and xBot (Web Bluetooth)
├── deviceInterface.ts
├── deviceStore.ts
├── flatFilesystem.ts           Flat file system rules of micro:bit and Calliope
├── roboticsLibraries.ts
└── simulatorFilesystem.ts

src/file_system/ directory#

This directory contains the browser-side file system layer. It coordinates local file operations, worker-based execution, and integrations for Git and OneDrive sync flows.

file_system/
├── git/
│   ├── gitAuth.ts                   Git auth token handling
│   ├── gitHeadTracker.ts            Track current Git HEAD
│   ├── gitOperations.ts             Main Git module
│   └── gitStatusMatrix.ts           Git change detection matrix
├── onedrive/
│   ├── oneDriveClient.ts            OneDrive API client wrapper
│   ├── oneDriveExporter.ts          Export to OneDrive handler
│   ├── oneDriveImporter.ts          Import from OneDrive handler
│   └── oneDriveStatusMatrix.ts      OneDrive change detection matrix
├── fileTypeUtils.ts                 File type detection (which viewer opens a file)
├── fileWorker.ts                    Web worker that owns the workspace file system
├── fileWorkerClient.ts              Main thread access to the file worker
├── fs_isogit_wrapper.ts             Isomorphic-git bridge
├── fs_main.ts                       Main filesystem API surface
├── sessionStorageManager.ts         Session storage state handling
└── FILESYSTEM.md                    Developer documentation of the file system

src/localisation/ directory#

Provides the available languages for the website as YAML translation files, with an index file to manage them.

localisation/
├── de.yaml
├── en.yaml
├── es.yaml
├── fr.yaml
├── hi.yaml
├── index.ts
├── it.yaml
├── ru.yaml
└── sk.yaml

src/pyodide/ directory#

This folder contains the integration of Pyodide (Python running in the browser via WebAssembly).

pyodide/
├── host_bridge/        Calls from the Python worker to the main thread (DOM, audio)
├── jythonAssets.ts     Access to the TigerJython assets
├── pyodideStore.ts
├── pyodideworker.ts
└── serviceWorker.ts

src/python/ directory#

This folder contains the core Python modules and libraries that are available in WebTigerPython. It includes educational frameworks (e.g. gturtle, gpanel, gamegrid), music and sound libraries (gmusic, JythonMusic, soundsystem), robotics integrations (oxocard, rootRobot, xBot) and database access.

python/
├── database1/
├── debugger/
├── forbiddenfruit/
├── gamegrid/
├── gmusic/
├── gpanel/
├── gturtle/
├── java/
├── JythonMusic/
├── music/
├── oxocard/
├── pyomqtt/
├── rootRobot/
├── runner/
├── soundsystem/
├── sqlite3Trial/
├── TigerPython/
├── turtle/
└── xBot/

The turtle graphics are rendered by the separate package @tigerpython/turtle-renderer (see Turtle Graphics).

src/sound/ directory#

This folder provides modules for handling audio features. It includes instrument definitions, a music store for managing playback, sound data utilities, and a text-to-speech component. Together, these files allow the application to generate, process, and play sounds programmatically.

sound/
├── instruments.d.ts
├── musicStore.ts
├── soundData.ts
└── textToSpeech.ts

src/ui/ directory#

This directory defines all the Vue components the UI is built upon. The most complex one is without any doubt the code editor the students are using to write code.

ui/
├── Alerts/
├── CanvasTabs/
├── Console/
├── Editor/
├── FileSystem/
├── GitWindows/
├── Infopage/
├── OneDriveWindows/
├── OptionsDrawer/
├── TopBar/
├── Tutorials/
├── UserInput/
│
├── ConsentForm.vue
├── MainWindow.vue
└── MainWindowPart.vue

src/main.ts#

This is the entry point into the Web App. In particular, it loads the Pinia state manager and Vuetify, the Material CSS framework used throughout the project, and applies the URL arguments.

src/App.vue#

This is the main component of the Vue app that is rendered into the #app element of the index.html file.

The component hierarchy is as follows:

App
├── TopBar
├── OptionsDrawer
├── MainWindow
├── UserInput
├── GitInfo
├── GitChangesConfirm
├── Infopage
└── ConsentForm

During the OAuth login (OneDrive), App shows the OAuthCallback page instead.