arc42 Konnektoren

1. Introduction and Goals

1.1. Requirements Overview

Konnektoren is a web-based learning platform focused on improving the understanding and usage of German grammar through gamification. It offers interactive challenges—ranging from multiple-choice questions to scenario-based tasks—targeted at both beginners and intermediate learners.

Main objectives:

  • Make learning German grammar engaging and effective.

  • Use gamification (points, levels, achievements) to motivate users and increase retention.

  • Provide measurable progress and feedback to learners and educators.

Core Features:

  • User profiles and progress tracking

  • Interactive grammar challenges

  • Visual progress maps

  • Leaderboards and achievements

  • Certificate and badge issuance (SSI-compatible)

Key Use Cases:

Use Case

Description

Create Profile

User sets up a personal profile name.

Participate in Challenges

User selects and completes grammar challenges.

Track Progress

User views progress via maps, achievements, and statistics.

Compete on Leaderboards

User compares performance with others.

Claim Certificates/Badges

User receives digital credentials for achievements.

1.2. Quality Goals

Quality Goal Scenario Priority

Usability

Users can intuitively navigate, start challenges, and view progress without training.

High

Reliability

The platform maintains >99.9% uptime and recovers quickly from failures.

High

Scalability

The system supports 1,000+ concurrent users with no performance degradation.

Medium

Performance

Challenge loading and user actions respond within 1 second in 95% of cases.

Medium

Security

All user data is encrypted in transit and at rest; certificates use digital signatures.

High

Maintainability

Modular codebase allows new features to be added with minimal impact.

Medium

1.3. Stakeholders

Role/Name Expectations

Product Owner

Product meets business and educational objectives; measurable impact.

Developers

Clear requirements, modern toolchain, documented APIs, CI/CD.

End Users (Students)

Fun, effective, and accessible learning experience.

Educational Institutions

Integration with curricula, reporting, and privacy compliance.

Support Team

Troubleshooting tools, clear documentation, rapid issue resolution.

Content Creators

Easy-to-use authoring tools, versioning, preview features.

Marketing Team

Features and updates to promote and grow user base.

2. Constraints

2.1. Technical Constraints

  • Platform built with web technologies: HTML, CSS, JavaScript, Rust (WASM).

  • Compatible with modern browsers: Chrome, Firefox, Safari, Edge.

  • Backend services in Rust, hosted on scalable cloud infrastructure.

  • Third-party integrations (payments, social media) must follow security best practices.

2.2. Organizational Constraints

  • The project should align with the educational goals and standards set by partner educational institutions.

  • All content must be reviewed and approved by language experts to ensure accuracy and quality.

  • The development team contributes on a voluntary basis, working in their free time as availability allows.

  • Development follows a continuous improvement approach, with updates and enhancements made as contributors’ time permits.

2.3. Legal Constraints

  • The platform must comply with all relevant data protection regulations (e.g., GDPR, CCPA) to ensure user privacy and data security.

  • All educational content must be original or properly licensed, with clear attribution where required, to avoid copyright infringement.

  • User consent must be obtained for any data collection, and users must be able to access, modify, or delete their personal data as required by law.

  • Third-party integrations (such as payment gateways or analytics) must adhere to industry standards for privacy and security.

  • Regular reviews should be conducted to ensure ongoing compliance with changing legal requirements and best practices.

3. Architecture Constraints

3.1. Technical Constraints

Constraint Explanation

Programming Language

All core libraries and backend services must be implemented in Rust to ensure compatibility with the Yew frontend and WebAssembly (WASM) compilation. This enables high performance, safety, and code reuse across frontend and backend.

Browser Compatibility

The application must support the latest versions of Chrome, Firefox, Safari, and Edge to maximize accessibility for users.

WebAssembly Support

The frontend must compile to WASM for efficient execution in browsers, leveraging Rust’s WASM toolchain.

Scalability

The system should use a serverless or cloud-native architecture to handle variable loads and minimize operational overhead.

Backend Services

Backend APIs and services must be written in Rust and deployed on scalable cloud infrastructure (e.g., Docker containers, serverless platforms).

Third-Party Integrations

Integrations (e.g., payment gateways, analytics) must use secure, standards-compliant APIs and minimize vendor lock-in.

3.2. Organizational and Political Constraints

Constraint Explanation

Data Privacy

All features must comply with GDPR and other relevant data protection laws, as the platform serves users in the EU and globally.

Budget Limitations

The project operates with a limited budget, relying on free/open-source tools and voluntary contributions. Use of paid third-party services must be justified and kept minimal.

Development Timeline

Development is ongoing and flexible, driven by contributors' availability and free time. There are no fixed deadlines, but continuous improvement is encouraged.

Stakeholder Involvement

Feedback from educators, students, and other stakeholders should be regularly solicited and incorporated into the design and development process.

Content Review

All educational content must be reviewed and approved by qualified language experts before publication.

3.3. Conventions

Constraint Explanation

Code Style Guidelines

All Rust code must follow the official Rust style guide (rustfmt) to ensure consistency and readability across the codebase.

Versioning Guidelines

Semantic Versioning (SemVer) is required for all releases to communicate changes and maintain compatibility.

Documentation Standards

All public APIs and core modules must be documented using Rustdoc. Additional architectural documentation should be maintained in AsciiDoc format.

Naming Conventions

Use clear, descriptive names for variables, functions, modules, and crates, following Rust community conventions and internal guidelines.

Testing Guidelines

Automated tests (unit, integration, and BDD) must be written for all new features and bug fixes. Code coverage should be monitored and improved over time.

Security Practices

Regularly audit dependencies for vulnerabilities (cargo audit), follow secure coding practices, and conduct periodic security reviews.

Continuous Integration

All code changes must pass CI checks, including formatting, linting, and tests, before merging.

4. Context and Scope

4.1. System Overview

system overview c4

This diagram provides a high-level overview of the Konnektoren system, showing the main components and their interactions. Users, educators, and content creators interact with the system via secure web protocols. Cloudflare acts as a CDN and proxy, while GitHub Pages hosts the static frontend. The core logic and leaderboard service run in containers, and external services handle credential issuance and payments.

4.2. Business Context

Communication Partner Inputs to System Outputs from System

Users (Learners)

Registration data, challenge answers, feedback

Learning progress, achievements, certificates, feedback

Content Creators

Educational content submissions, updates

Content publication status, feedback

Payment Gateway

Payment confirmations

Access to premium features, receipts

External Credential Issuer

Credential requests

Verifiable credentials (badges, certificates)

Explanation of external domain interfaces

The system interfaces with individual users, educators, and content creators. It receives registration details, challenge responses, content submissions, and payment confirmations. Outputs include learning progress, achievements, certificates, analytics, and feedback.

4.3. Technical Context

I/O Channel Protocol

User registration data

Internet

HTTPS

Grammar test answers

Internet

HTTPS

Learning progress

Internet

HTTPS

Detailed reports

Internet

HTTPS

Explanation of technical interfaces

The technical architecture leverages modern web protocols to ensure secure and efficient data transmission. User data and responses are transmitted over HTTPS, ensuring privacy and security. Detailed reports and learning progress are also transmitted over HTTPS.

5. Solution Strategy

5.1. Technology Decisions

5.1.1. Web-Based Platform

Konnektoren is designed as a web-based platform to ensure accessibility and ease of maintenance. This approach allows users to access the system across various devices without the need for native applications, reducing development complexity and improving user reach.

5.1.2. Rust Programming Language

We chose Rust as the primary programming language for the Konnektoren project for several key reasons:

  1. Performance: Rust’s zero-cost abstractions and lack of a garbage collector enable high-performance code execution, crucial for complex language learning algorithms and responsive user interfaces.

  2. Safety: Rust’s strict compile-time checks and ownership model eliminate entire classes of bugs, enhancing the overall security and reliability of the application.

  3. WebAssembly Compatibility: Rust’s excellent support for WebAssembly (Wasm) allows us to run complex logic directly in the browser at near-native speed, improving performance and reducing server load.

  4. Minimized Server-side Data: By leveraging Rust’s WebAssembly capabilities, we can run most of our application logic in the frontend, minimizing the amount of user data stored on servers. This approach enhances privacy and reduces server costs.

5.1.3. Yew Framework

The Yew framework was selected as our front-end solution for the following reasons:

  1. Rust Ecosystem Integration: Yew, being Rust-based, allows us to maintain a consistent language ecosystem throughout our stack, simplifying development and maintenance.

  2. Component-based Architecture: Yew’s component-based model aligns with our preference for modular, reusable code, enhancing maintainability and development efficiency.

  3. WebAssembly Optimization: Yew’s seamless integration with WebAssembly enables us to create high-performance web applications that rival native app performance.

  4. Strong Typing: Leveraging Rust’s type system, Yew provides strong typing for components and their properties, catching potential errors at compile-time rather than runtime.

5.1.4. Axum Framework

For our backend needs, we’ve chosen the Axum framework:

  1. Performance: Built on top of Tokio, Axum leverages a high-performance, asynchronous runtime for efficient handling of concurrent operations.

  2. Security: Axum inherits Rust’s strong security guarantees and provides additional features for building secure web services.

  3. Tokio Ecosystem: Being part of the Tokio ecosystem gives us access to a wide range of well-maintained, high-quality libraries and tools.

  4. Cost-effectiveness: Axum’s efficiency allows us to handle more requests with fewer resources, leading to a more cost-effective backend infrastructure.

5.2. Architectural Decisions

5.2.1. GitHub Pages Hosting

The front-end application is hosted on GitHub Pages, providing a cost-effective and scalable solution for serving static content. This choice aligns with our goal of minimizing operational costs while ensuring high availability.

5.2.2. Single Page Application (SPA)

The front end is built as a SPA, interacting with back-end services via RESTful APIs. This architecture supports a seamless and responsive user experience by reducing page reloads and enabling dynamic UI updates.

5.2.3. Serverless Architecture

We’ve adopted a serverless architecture to reduce operational overhead and improve scalability. By leveraging cloud services like Cloudflare Workers, we can focus on developing features rather than managing infrastructure.

5.2.4. Cloudflare Proxy

Cloudflare Workers are used as a proxy to secure communication between the front end and back end, providing an additional layer of security and performance optimization.

5.3. Achieving Quality Goals

5.3.1. Usability and User Engagement

To achieve high usability, we’ve designed an intuitive and engaging UI/UX, leveraging gamification techniques to motivate learners. Regular user testing ensures that the interface meets the needs of our target audience.

5.3.2. Reliability and Scalability

We utilize cloud-based services and modern DevOps practices to ensure system reliability and scalability. Automated testing and deployment facilitate continuous improvement and responsiveness to user demands.

5.4. Organizational Decisions

5.4.1. Agile Development Process

The project adopts an Agile methodology to allow for flexibility in development and to efficiently incorporate feedback. This process supports iterative development and continuous improvement, aligning with our quality goals.

By implementing these strategies, we aim to create a robust, performant, and maintainable application that provides a smooth and responsive user experience for language learners while keeping user data private and minimizing server-side costs.

6. Building Block View

6.1. Whitebox Overall System

The Konnektoren project is organized into a workspace containing multiple crates, each representing a different part of the system’s functionality. The following PlantUML diagram provides an overview of the top-level building blocks and their dependencies.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-building-blocks-c4.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-building-blocks-c4.puml[]
Motivation

This decomposition allows for modular development and testing of each part of the system. The core functionalities are implemented in the konnektoren-core crate, which is then utilized by the TUI and Yew crates for different user interfaces. The konnektoren-tests crate ensures that all components are thoroughly tested.

Contained Building Blocks

Name

Responsibility

konnektoren-core

Contains the core logic and functionalities of the Konnektoren project.

konnektoren-tests

Contains tests for the core functionalities and other crates.

konnektoren-tui

Provides a text user interface for the Konnektoren project.

konnektoren-yew

Provides a web frontend using the Yew framework.

6.1.1. konnektoren-core

Purpose/Responsibility

The konnektoren-core crate is responsible for implementing the main logic and functionalities of the Konnektoren project, such as handling grammar challenges, tracking user progress, and managing gamification elements.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-core-structure-c4.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-core-structure-c4.puml[]

6.1.2. konnektoren-core Detailed Structure

The konnektoren-core crate is composed of several modules, each responsible for a specific aspect of the core functionality. Here’s a more detailed diagram of its internal structure:

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-core-detailed-structure.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-core-detailed-structure.puml[]
Contained Building Blocks

Name

Responsibility

challenges

Contains all challenge-related modules and implementations

game

Manages game logic, paths, and states

certificates

Handles certificate generation and verification

player_profile

Manages user profiles and progress

session

Handles user sessions and state management

commands

Implements command pattern for game actions

This detailed diagram provides a clearer picture of the internal structure of the konnektoren-core crate, showing the relationships between different modules and packages.

6.2. Level 2: Command Structure

The command structure in konnektoren-core is designed to handle various actions within the game. It consists of the following main components:

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/command-structure.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/command-structure.puml[]

  • CommandTrait: Defines the basic behavior for all commands in the game.

  • Command: An enum representing all possible commands, including both game-level and challenge-level commands.

  • GameCommand: Enum for game-level commands like navigating between challenges.

  • ChallengeCommand: Enum for challenge-level commands like navigating tasks or solving options.

This command structure allows for a unified interface to execute various actions within the game, providing flexibility and extensibility for future additions.

6.3. Level 2: Event Structure

The event structure in konnektoren-core is designed to handle various occurrences within the game. It consists of the following main components:

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/event-structure.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/event-structure.puml[]

  • Event: An enum representing all possible events, including both game-level and challenge-level events.

  • GameEvent: Enum for game-level events like game start.

  • ChallengeEvent: Enum for challenge-level events like solving questions or completing challenges.

This event structure allows for a unified interface to represent various occurrences within the game, providing flexibility and extensibility for future additions.

6.3.1. Event Types

Game Events

  • Started: Triggered when a new game session begins.

Challenge Events

  • SolvedCorrect(usize): Triggered when a user solves a challenge correctly. The usize parameter represents the index of the solved question.

  • SolvedIncorrect(usize): Triggered when a user solves a challenge incorrectly. The usize parameter represents the index of the incorrectly solved question.

  • Started: Triggered when a user starts a new challenge.

  • Completed: Triggered when a user completes a challenge.

6.4. Level 2: Event and Command Handling

6.4.1. EventBus

The EventBus is a central component for handling events in the Konnektoren system. It allows for decoupled communication between different parts of the application.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/eventbus-structure.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/eventbus-structure.puml[]

Key responsibilities: - Allows components to subscribe to specific event types - Publishes events to all subscribed handlers - Provides a decoupled way for components to communicate

6.4.2. CommandBus

The CommandBus is responsible for handling and executing commands in the Konnektoren system. It centralizes command processing and allows for separation of command dispatch and execution.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/commandbus-structure.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/commandbus-structure.puml[]

Key responsibilities: - Allows registration of command handlers for specific command types - Dispatches commands to appropriate handlers - Provides a centralized way to execute game actions

GameController

The central component managing game state and coordinating game operations:

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/game_controller.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/game_controller.puml[]

  • Maintains thread-safe game state using Arc<Mutex<GameState>>

  • Houses EventBus and CommandBus for communication

  • Manages persistence of game state

  • Coordinates plugin initialization and lifecycle

    Key Responsibilities

  • Game state management

  • Command handling and dispatch

  • Event coordination

  • Plugin management

  • State persistence

PluginManager

Handles the registration and lifecycle of plugins:

Key Responsibilities

  • Plugin registration and storage

  • Plugin initialization sequence

  • Plugin lifecycle management

  • Plugin coordination

6.4.3. Built-in Plugins

GameXpPlugin

Manages experience points in the game:

  • Listens for challenge completion events

  • Updates player XP based on performance

  • Persists XP changes to game state

DebugPlugin

Provides debugging capabilities:

  • Logs game and challenge commands

  • Helps with development and troubleshooting

  • Configurable logging levels

ChallengeFinishPlugin

Handles challenge completion:

  • Processes challenge completion events

  • Updates game state accordingly

  • Triggers relevant achievements

6.4.4. Plugin Lifecycle

  1. Registration: Plugins are registered with the GameController

  2. Initialization: The PluginManager initializes all registered plugins

  3. Loading: Plugins are loaded with a reference to the GameController

  4. Operation: Plugins interact with the game through events and commands

  5. Unloading: Plugins are unloaded when the game session ends

6.4.5. Integration with Event and Command System

The plugin system integrates closely with the Event and Command system:

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/plugin-integration.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/plugin-integration.puml[]

6.4.6. KonnektorenJs

The KonnektorenJs struct provides a bridge between the Rust core functionality and JavaScript, enabling seamless integration of Konnektoren features in web applications.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-js-structure.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-js-structure.puml[]

The KonnektorenJs struct encapsulates several handlers, each responsible for a specific aspect of the JavaScript integration:

  • ChallengeHandler: Manages challenge data in the JavaScript environment.

  • CommandHandler: Handles command execution between Rust and JavaScript.

  • EventHandler: Manages event handling between Rust and JavaScript.

  • I18nHandler: Handles internationalization data.

  • JsExecutor: Executes JavaScript code from Rust.

  • ResultHandler: Manages result data in the JavaScript environment.

Key functionalities:

  1. Challenge Data Management: Set and retrieve challenge data in the JavaScript environment.

  2. Result Handling: Set and retrieve challenge result data.

  3. Event Handling: Expose functions to handle events between Rust and JavaScript.

  4. Command Execution: Enable execution of commands between Rust and JavaScript.

  5. JavaScript Execution: Execute JavaScript code from Rust.

  6. Internationalization: Set and manage internationalization data.

  7. Challenge Completion: Finish challenges and handle results.

This structure allows for efficient communication between the Rust core and JavaScript, enabling the development of interactive web applications using Konnektoren’s functionality.

6.4.7. konnektoren-yew

Purpose/Responsibility

The konnektoren-yew crate is responsible for providing a web-based user interface for the Konnektoren project using the Yew framework.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-yew-structure-c4.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/konnektoren-yew-structure-c4.puml[]
Contained Building Blocks

Name

Responsibility

App

Main application component that sets up routing and global state.

Components

Reusable UI components used across different pages.

Pages

Individual page components for different views in the application.

Services

Interfaces with konnektoren-core and handles API calls.

Managers

Yew components that manage state and data flow for specific features or parts of the UI

6.5. Level 2: Challenge Rating System

The challenge rating system is a crucial part of the Konnektoren project, allowing users to provide feedback on challenges and view aggregate ratings.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/challenge-rating-system.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/challenge-rating-system.puml[]
Motivation

This architecture allows for a clear separation of concerns between the user interface, business logic, and data storage. It enables efficient collection and retrieval of user feedback, which can be used to improve the quality of challenges and enhance the user experience.

Contained Building Blocks

Name

Responsibility

Frontend

Provides the user interface for viewing challenges, submitting ratings/reviews, and displaying average ratings.

Backend API

Processes incoming ratings/reviews, retrieves average ratings, and manages communication with the Redis database.

Database

Stores all challenge-related data, including user ratings and reviews, using Redis for fast data access.

6.6. Level 3: Frontend Components

This level provides a more detailed view of the frontend components in the Konnektoren Yew application.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/frontend-components-c4.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/frontend-components-c4.puml[]
Contained Building Blocks

Name

Responsibility

ChallengeList

Displays a list of available challenges to the user.

ChallengeDetail

Shows detailed information about a specific challenge and allows users to attempt it.

RatingForm

Allows users to submit ratings and reviews for challenges.

LeaderBoard

Displays the top-performing users based on their challenge results.

UserProfile

Shows user information, progress, and achievements.

6.7. Level 3: Yew Game Controller and Repository Providers

The Game Controller Provider and Repository Provider are crucial components in the Konnektoren Yew frontend application. They manage the game state, repository access, and provide these services throughout the component tree.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/game-controller-and-repository-providers.pum ...
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/game-controller-and-repository-providers.puml[]

6.7.1. GameControllerProvider

The GameControllerProvider is a Yew component that wraps the entire application and provides the GameController context to all child components.

Responsibilities

  • Initialize the GameController with default game state

  • Provide the GameController context to child components

  • Manage the lifecycle of the GameController

GameControllerContext

The GameControllerContext is a struct that holds a reference to the GameController and is passed down the component tree.

Custom Hooks for GameController

The provider includes several custom hooks to easily access different parts of the game state:

  • use_game_controller(): Returns the GameControllerContext

  • use_game_state(): Returns the current GameState

  • use_event_bus(): Returns the EventBus for subscribing to and publishing events

  • use_command_bus(): Returns the CommandBus for dispatching commands

Example Usage:

#[function_component(MyComponent)]
fn my_component() -> Html {
    let game_state = use_game_state();
    let command_bus = use_command_bus();

    // Use game_state and command_bus in your component logic
    // ...
}

6.7.2. RepositoryProvider

The RepositoryProvider is a Yew component that provides access to various repositories throughout the component tree.

Responsibilities

  • Initialize repositories with appropriate storage backends

  • Provide the repository context to child components

  • Manage the lifecycle of repositories

RepositoryContext

The RepositoryContext is a struct that holds references to various repositories (e.g., CertificateRepository, SettingsRepository, ProfileRepository) and is passed down the component tree.

Custom Hooks for Repositories

The provider includes several custom hooks to easily access different repositories:

  • use_certificate_repository(): Returns the CertificateRepository

  • use_settings_repository(): Returns the SettingsRepository

  • use_profile_repository(): Returns the ProfileRepository

Example Usage:

#[function_component(SettingsComponent)]
fn settings_component() -> Html {
    let settings_repository = use_settings_repository();

    // Use settings_repository in your component logic
    // ...
}

6.7.3. Additional Repository Hooks

To simplify common repository operations, additional hooks are provided:

use_settings

The use_settings hook provides easy access to the application settings.

#[hook]
pub fn use_settings() -> UseStateHandle<Settings> {
    let settings_repository = use_settings_repository();
    let settings = use_state(|| Settings::default());

    use_effect_with((),
        move |_| {
            let settings = settings.clone();
            wasm_bindgen_futures::spawn_local(async move {
                if let Ok(Some(loaded_settings)) = settings_repository.get_settings(SETTINGS_STORAGE_KEY).await {
                    settings.set(loaded_settings);
                }
            });
            || ()
        },
    );

    settings
}
use_certificate

The use_certificate hook provides access to the user’s certificate data.

#[hook]
pub fn use_certificate() -> UseStateHandle<Option<Certificate>> {
    let certificate_repository = use_certificate_repository();
    let certificate = use_state(|| None);

    use_effect_with((),
        move |_| {
            let certificate = certificate.clone();
            wasm_bindgen_futures::spawn_local(async move {
                if let Ok(Some(loaded_certificate)) = certificate_repository.get_certificates(CERTIFICATE_STORAGE_KEY).await {
                    certificate.set(Some(loaded_certificate));
                }
            });
            || ()
        },
    );

    certificate
}
use_profile

The use_profile hook provides access to the user’s profile data.

#[hook]
pub fn use_profile() -> UseStateHandle<PlayerProfile> {
    let profile_repository = use_profile_repository();
    let profile = use_state(|| PlayerProfile::default());

    use_effect_with((),
        move |_| {
            let profile = profile.clone();
            wasm_bindgen_futures::spawn_local(async move {
                if let Ok(Some(loaded_profile)) = profile_repository.get_profile(PROFILE_STORAGE_KEY).await {
                    profile.set(loaded_profile);
                }
            });
            || ()
        },
    );

    profile
}

These hooks simplify data access and state management in components, allowing for more concise and readable code when working with repository data.

6.8. Yew Managers

Managers in the Yew frontend are special components that handle state management and data loading for specific parts of the application. They typically use the Context API or custom hooks to provide data and functionality to their child components.

6.8.1. Types of Managers:

  • ProfilePointsManager: This manager handles the loading and updating of the user’s profile points. It fetches the profile data from the ProfileRepository and makes it available to child components through properties.

  • InboxManager: This manager is responsible for loading and managing the user’s inbox messages. It retrieves inbox data from a YAML file and the InboxRepository. It also provides functionality to mark messages as read and persist this state.

6.8.2. Benefits of using Managers:

  • Centralized State Management: Instead of scattering state management logic across multiple components, managers provide a single source of truth for specific data.

  • Improved Data Loading: Managers can handle asynchronous data fetching from repositories or APIs, simplifying data loading in child components.

  • Code Reusability: Managers encapsulate common logic related to specific data or features, promoting code reuse and reducing redundancy.

  • Better Organization: Using managers helps organize your Yew application and separate concerns, making the codebase easier to understand and maintain.

6.9. Level 4: Data Model

The data model is a crucial part of the Konnektoren system, defining the structure and relationships of the core entities. Understanding this model is essential for developers working on the system and for maintaining data integrity across different components.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/data-model.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/data-model.puml[]

Key Entities:

  • PlayerProfile: Represents a user’s profile information, including their accumulated experience points (XP).

  • Challenge: Encapsulates a single challenge, including its type, configuration, and result.

  • GamePath: Represents a sequence of challenges that form a learning path.

  • GameState: Tracks the current state of a player’s game, including their position in a game path and current challenge.

  • Session: Links a player profile to their current game state.

This data model supports the core functionality of the Konnektoren system, allowing for flexible challenge creation, user progress tracking, and game state management. The relationships between entities enable features like personalized learning paths and progress persistence across sessions.

6.10. Achievement System

The achievement system consists of the following components:

  • Achievement Configuration: Stored in YAML format, defining various achievements and their conditions.

  • Achievement Evaluator: Evaluates the user’s progress against the achievement conditions.

  • Game Statistics: Collects and provides statistics about the user’s game progress.

  • Achievement Display: Shows unlocked and locked achievements in the frontend.

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ]

@startuml
Unresolved directive in src/05_building_block_view.adoc - include::diagrams/achievement-system.puml[]
^^^^^
 Syntax Error?

Unresolved directive in src/05_building_block_view.adoc - include::diagrams/achievement-system.puml[]

7. Runtime View

7.1. Profile Update Scenario

This scenario demonstrates how a user updates their profile name, with data stored locally for privacy and offline support.

profile update

Steps:

  1. User opens the profile page in the Konnektoren Yew web app.

  2. User updates their name.

  3. WebApp saves the updated name in browser local storage.

  4. LocalStorage confirms the save.

  5. WebApp displays a success message.

Architectural relevance: Demonstrates privacy-preserving local data management and immediate UI feedback.

7.2. Challenge Selection Scenario

This scenario shows how a user selects a challenge on the map, with access control and error handling.

user selects challenge

Steps:

  1. User opens the map page.

  2. WebApp requests profile and game state from Core.

  3. Core retrieves data from LocalStorage.

  4. Data flows back to WebApp, which displays the map.

  5. User selects a challenge.

  6. WebApp checks requirements with Core.

  7. If locked, error is shown; if unlocked, challenge info is displayed and user can start the challenge.

Architectural relevance: Shows access control, error handling, and data flow between frontend, core logic, and local storage.

7.3. Challenge Participation Scenario

This scenario covers the full flow of a user participating in a challenge, including evaluation and awarding points.

challenge participation

Steps:

  1. User starts a challenge.

  2. Challenge data is loaded and displayed.

  3. User submits answers.

  4. Answers are evaluated; results are returned and shown.

  5. Points are awarded and user profile is updated.

Architectural relevance: Demonstrates modular evaluation, state updates, and feedback loop.

7.4. Leaderboard and Certificate Scenario

This scenario illustrates how a user claims a certificate and interacts with the leaderboard.

leaderboard certificate

Steps:

  1. User views profile and claims certificate.

  2. Certificate is generated and stored via backend API.

  3. User views leaderboard, which is fetched from backend.

Architectural relevance: Shows integration with backend APIs, certificate generation, and leaderboard data flow.

7.5. Verifiable Credential Issuance Scenario

This scenario demonstrates how a user receives a verifiable credential (badge) after completing challenges.

vc issuance c4

Steps:

  1. User completes challenges.

  2. Frontend verifies completion with Core.

  3. Achievement is confirmed.

  4. Frontend requests credential from external issuer.

  5. Credential is issued via OpenID4VC.

  6. Frontend displays QR code for user to claim badge.

Architectural relevance: Highlights SSI integration and secure credential issuance.

7.6. Event and Command Handling Scenario

This scenario shows how the EventBus and CommandBus decouple actions and notifications in the system.

event command scenario

Steps:

  1. UI publishes a command to CommandBus.

  2. CommandBus executes the command via Game Logic.

  3. Game Logic loads the next challenge.

  4. Game Logic publishes an event to EventBus.

  5. EventBus notifies UI, which updates the display.

Architectural relevance: Demonstrates modular, event-driven architecture for maintainability and extensibility.

7.7. Game Controller Interaction Scenario

This scenario demonstrates how the GameController manages state and coordinates commands, events, and persistence.

game controller interaction

Steps:

  1. Client publishes a command to GameController.

  2. GameController forwards to CommandBus.

  3. CommandBus calls back to GameController to handle the command.

  4. GameController updates GameState.

  5. GameController publishes an event to EventBus.

  6. GameController saves state via Persistence.

  7. EventBus notifies Client of the state change.

Architectural relevance: Shows orchestration of state, events, and persistence for robust game management.

8. Deployment View

8.1. Overview

The konnektoren.help platform uses a modern, cloud-native deployment model. The frontend is a static WebAssembly (WASM) application hosted on GitHub Pages, delivered globally via Cloudflare CDN and proxy. The backend leaderboard service is a Rust Axum server running inside a Docker container, communicating via REST API.

8.2. Infrastructure Level 1: High-Level Deployment

Deployment Overview Diagram

deployment overview

Motivation

  • Decentralized, scalable architecture for global reach and low latency.

  • Separation of concerns: static frontend, containerized backend, and managed CDN/proxy.

Quality & Performance Features

  • Cloudflare provides caching, DDoS protection, SSL termination, and global distribution.

  • Docker enables reproducible, isolated, and scalable backend deployments.

  • REST API ensures loose coupling between frontend and backend.

Mapping of Building Blocks to Infrastructure

Building Block Infrastructure Component Notes

WASM Frontend

GitHub Pages + Cloudflare CDN

Built and deployed via GitHub Actions; static hosting, global delivery

Axum Leaderboard

Docker Host (Cloud/VM)

Containerized Rust backend

Leaderboard Database

Managed DB (e.g., PostgreSQL)

Persistent scores, scalable

CDN/Proxy

Cloudflare

Caching, SSL, API routing

8.3. Infrastructure Level 2: Detailed Components

8.3.1. GitHub Pages & Cloudflare CDN

Frontend Hosting Diagram

github pages deployment

  • Users access the WASM frontend via Cloudflare, which caches and accelerates delivery.

  • GitHub Pages hosts the static assets, with Cloudflare providing SSL and edge caching.

8.3.2. Axum Server in Docker

Backend Deployment Diagram

axum server deployment

  • The Axum server runs in a Docker container, exposing REST APIs for leaderboard management.

  • The backend communicates with a managed database (e.g., PostgreSQL, SQLite, or cloud DB).

8.4. Scaling, Monitoring, and Security

  • Scaling: Docker containers can be replicated for horizontal scaling. Cloudflare automatically scales CDN delivery.

  • Monitoring: Use Cloudflare analytics for traffic and health.

  • Security: All traffic is encrypted (HTTPS). Cloudflare provides DDoS protection and WAF. Backend containers run as non-root and are regularly updated.

8.5. Deployment Automation

  • CI/CD: GitHub Actions automates build, test, and deployment for both frontend and backend.

9. Cross-cutting Concepts

9.1. Modular Core Library and UI Components

The konnektoren project centers on a modular core library containing all business logic, decoupled from any specific user interface. This enables code reuse across multiple applications (e.g., web, Telegram) and simplifies maintenance and extension. Reusable UI components are provided for rapid integration and consistent user experience.

core library

Diagram: Modular architecture enables UI components to interact with core business logic, supporting multiple frontends.

Benefits:

  • Separation of concerns: UI and logic evolve independently.

  • Code reuse: Core logic shared across platforms.

  • Easier testing and extension.

9.2. Command and Event Handling Pattern

Konnektoren uses a command/event pattern, primarily via the GameController, to manage game state and user interactions. Commands trigger actions; events notify subscribers of changes.

command event pattern

Advantages:

  • Decouples components for maintainability.

  • Enables extensibility by adding new command/event types.

  • Clear control and data flow.

  • Facilitates testing and mocking.

9.3. Web3-Oriented Architecture

The system is designed with web3 principles: minimal server-side storage, privacy by default, and user empowerment. User data (except leaderboard) is stored client-side, with encryption and digital signatures for verification.

web3 architecture

Diagram: User data is stored locally; only essential data (leaderboard) is centralized.

Benefits:

  • Enhanced privacy and user control.

  • Reduced attack surface.

  • Offline support.

9.4. Encryption and Digital Signatures

Data integrity and security are ensured through encryption and digital signatures. Certificates and sensitive data are signed and verified using industry-standard cryptography (e.g., Ed25519).

encryption diagram

Diagram: Encryption and signature verification are performed client-side, with server-side certificate authority for validation.

Key Points:

  • Data is encrypted at rest and in transit.

  • Certificates are signed and verified without central authority.

  • Security is a first-class concern.

9.5. Privacy: Minimal Backend Logging and Analytics

To maximize privacy, konnektoren.help does not use backend logging. Google Analytics is used sparingly, only for product improvement and in compliance with privacy standards.

Best Practices:

  • No personal data is logged server-side.

  • Analytics are anonymized and opt-in where possible.

9.6. Achievement System

The achievement system motivates users and recognizes progress in learning German grammar.

9.6.1. Overview

  1. Achievements are defined in YAML configuration.

  2. User progress is tracked in Challenge History.

  3. Achievement Evaluator checks progress against achievement conditions.

  4. Unlocked achievements are displayed in the frontend.

9.6.2. Components

achievement system

Component Roles:

  • Achievement Configuration: YAML file with achievement definitions.

  • Challenge History: Tracks completed challenges and performance.

  • Game Statistics: Aggregates challenge data for evaluation.

  • Achievement Evaluator: Determines unlocked achievements.

  • Frontend: Displays achievements to users.

9.6.3. Implementation

  • AchievementDefinition: Metadata and condition for each achievement.

  • AchievementEvaluator: Evaluates achievements based on statistics.

  • GameStatistics: Calculates stats from challenge history.

Frontend requests updated achievement info and displays progress and new achievements.

9.7. Self-Sovereign Identity (SSI) for Badges

Konnektoren uses SSI principles for issuing achievement badges, empowering users and enhancing privacy.

ssi badge concept

Why SSI for badges?

  1. User Control: Users own and manage their credentials.

  2. Portability: Badges can be stored in any compatible SSI wallet.

  3. Privacy: No centralized storage of achievements.

  4. Verifiability: Third parties can verify badges without contacting Konnektoren.

  5. Interoperability: Uses standard formats (Verifiable Credentials, OpenBadges).

Architectural relevance: SSI integration aligns with decentralized, privacy-first design and future-proofs achievement credentials.

Unresolved directive in README.adoc - include::09_testing_strategy.adoc[]

10. Quality Requirements

10.1. Quality Tree

quality tree

The quality tree breaks down key quality goals of the konnektoren.help project, including performance, security, scalability, usability, maintainability, accessibility, and internationalization.

10.2. Quality Scenarios

Quality Attribute Scenario Description

Performance

95% of user interactions (e.g., opening a challenge, updating the leaderboard) complete within 1 second. WASM binaries load quickly even on low-bandwidth connections.

Security

All user data is encrypted in transit (HTTPS) and at rest. Digital certificates are verified using Ed25519 signatures. No sensitive data is stored server-side unless explicitly consented.

Scalability

The system supports at least 1,000 concurrent users and can handle traffic spikes without downtime or significant slowdowns.

Usability

Users can register, start challenges, and view leaderboards with minimal guidance. The UI is intuitive and consistent across devices and platforms.

Maintainability

New features or bug fixes can be added with minimal impact on existing functionality. The codebase is modular, well-documented, and covered by automated tests.

Accessibility

The platform meets WCAG 2.1 AA standards. Users with disabilities can navigate and use all features.

Internationalization

The UI and content support multiple languages. Users can switch languages seamlessly, and translations are accurate.

10.3. Detailed Quality Requirements

10.3.1. Performance

  • WebAssembly (WASM) is used for near-native browser performance.

  • Static assets are served via Cloudflare CDN to minimize latency.

  • Core algorithms are profiled and optimized for efficiency.

  • WASM binary size is kept low for fast initial load.

  • Performance is monitored and tested across target browsers and devices.

10.3.2. Security

  • All user data is encrypted at rest using AES-256 or equivalent.

  • HTTPS is enforced for all communications.

  • Digital certificates use Ed25519 signatures for authenticity.

  • Minimal server-side data storage reduces attack surface.

  • Regular security audits and dependency vulnerability scans (cargo audit) are performed.

  • Privacy compliance (GDPR, CCPA) is maintained.

10.3.3. Scalability

  • Serverless architecture enables automatic scaling based on demand.

  • Static content is hosted on GitHub Pages for high scalability.

  • Leaderboard and backend services are containerized for horizontal scaling.

  • Load testing is performed to validate scalability targets.

10.3.4. Usability

  • Responsive web design ensures consistent experience across desktop and mobile.

  • Gamification elements (points, badges, leaderboards) increase engagement.

  • User flows are tested and refined based on feedback.

  • UI components are reused and versioned for consistency.

  • Onboarding and help features are available for new users.

10.3.5. Maintainability

  • Codebase adheres to Rust’s official style guide (rustfmt).

  • Modular architecture enables isolated updates and feature additions.

  • Comprehensive unit, integration, and BDD tests are maintained.

  • Inline documentation for all public APIs; architectural docs in AsciiDoc.

  • CI/CD pipelines enforce code quality and test coverage.

10.3.6. Accessibility

  • All interactive elements are keyboard-accessible.

  • Sufficient color contrast and scalable fonts are used.

  • ARIA attributes and semantic HTML are implemented.

  • Accessibility is tested with automated tools and real users.

10.3.7. Internationalization

  • All UI text and content are translatable via i18n framework.

  • Language switching is available in the UI.

  • Translations are reviewed for accuracy and completeness.

  • Unicode and RTL language support is included.

11. Risks and Technical Debts

Risk/Technical Debt Description and Mitigation

Client-Side Data Storage Risks

Storing most user data client-side (browser/local storage) risks data loss if users clear their browser, switch devices, or lose access.

Mitigation: Provide clear backup/export instructions. Offer optional encrypted server-side backups. Educate users about risks.

Client-Side Cryptography and Signature Verification

Improper implementation of client-side encryption or digital signatures can lead to data leaks, spoofed certificates, or compromised privacy.

Mitigation: Use audited, well-established cryptographic libraries. Conduct regular security audits and penetration testing. Stay updated on cryptography best practices.

WebAssembly (WASM) Performance and Compatibility

Large WASM binaries or poor browser support can cause slow load times, especially on low-bandwidth connections or older devices.

Mitigation: Optimize binary size, use code splitting/lazy loading, and profile performance across target browsers. Provide fallback UI for unsupported environments.

Reliance on Third-Party Services

Downtime, API changes, or discontinued services (e.g., Cloudflare, payment gateways, analytics) can disrupt platform functionality.

Mitigation: Design for graceful degradation. Monitor service status. Maintain alternative providers or backup solutions for critical services.

Docker Container Security

Leaderboard and backend services running in Docker containers may be vulnerable if images are outdated, misconfigured, or run as root.

Mitigation: Use minimal, regularly updated images. Enforce non-root users. Scan containers for vulnerabilities. Apply security patches promptly.

Axum Framework Maturity

Axum, while promising, is newer and may lack mature documentation or community support compared to older Rust frameworks.

Mitigation: Track Axum releases and security advisories. Keep code modular to allow framework migration if needed. Engage with the Axum community.

Insufficient Backend Logging

Lack of backend logging limits visibility into production issues, making debugging and incident response difficult.

Mitigation: Implement privacy-compliant, selective logging for critical events. Use log aggregation tools for monitoring.

Multi-Environment Deployment Complexity

Managing development, staging, and production deployments can lead to configuration drift and inconsistent environments.

Mitigation: Use containerization (Docker) and Infrastructure as Code (e.g., Terraform, Ansible) to standardize deployments. Automate environment setup and configuration.

UI Component Reuse Technical Debt

Sharing UI components across web and Telegram apps can cause compatibility issues if core components change without proper versioning.

Mitigation: Maintain strict version control and documentation for shared components. Test compatibility before upgrades. Use semantic versioning.

Limited SSI Wallet and Library Support

SSI badge adoption depends on wallet and library support, which is currently limited and sometimes unstable.

Mitigation: Monitor SSI ecosystem for improvements. Provide fallback achievement display for users without SSI wallets. Contribute to open-source SSI projects.

Rust/WASM Toolchain Upgrades

Frequent updates to Rust, WASM, or related toolchains may introduce breaking changes or require refactoring.

Mitigation: Pin toolchain versions in CI. Test upgrades in staging before production. Monitor Rust/WASM release notes.

Accessibility and Internationalization Gaps

Rapid feature development may overlook accessibility (a11y) or internationalization (i18n), limiting usability for some users.

Mitigation: Include a11y and i18n checks in code reviews. Use automated tools to detect issues. Prioritize improvements based on user feedback.

12. Glossary

Symbol / Term Definition Example / Notes

Konnektoren

German grammatical connectors (e.g., "weil", "obwohl")

Used to link clauses and express relationships in sentences.

🧩 Challenge

An interactive exercise or task for the user

Multiple-choice, gap-fill, sorting, etc.

🏆 Achievement

A milestone or badge earned by completing challenges

"XP Master", "Challenge Champion"

📈 Progress Map

Visual representation of user progress

Shows completed challenges and paths.

👤 Profile

User account with personal data and progress

Includes XP, achievements, and history.

🗂 Game Path

A sequence of challenges forming a learning journey

"Konnektoren Path", "Past Tense Path"

🥇 Leaderboard

Ranking of users based on performance

Displays top scorers and recent achievements.

🛡️ Certificate

Digital credential issued for achievements

SSI-compatible, verifiable badge.

📝 Content Creator

Contributor who authors or updates educational material

Can submit new challenges or lessons.

🌐 Frontend

Web-based user interface built with Yew and WASM

Runs in browser, interacts with backend.

⚙️ Core

Business logic and game mechanics

Handles challenge evaluation, progress tracking.

📦 Backend Service

Server-side component for APIs and data management

Rust-based, cloud-hosted.

🗃️ Leaderboard Service

Manages user rankings and scores

Docker container, REST API.

🔒 GDPR

General Data Protection Regulation

Ensures user privacy and data security.

💳 Payment Gateway

Service for handling payments

Used for premium features.

🛠️ Rust

Programming language used for core and backend

Enables WASM compilation and safety.

🕸️ WASM

WebAssembly, binary format for running code in browsers

Used for high-performance frontend.

🚀 Yew

Rust framework for building web frontends

Compiles to WASM, used for UI.

📚 SSI

Self-Sovereign Identity, decentralized credential standard

Used for certificates and badges.