Development Guide

Development Guide

This guide is for developers who want to contribute to AkademiTrack or understand its technical architecture.

Project Overview

Repository: https://github.com/CyberGutta/AkademiTrack

Tech Stack:

• Language: C# (.NET)
• UI Framework: Avalonia UI (cross-platform)
• HTTP Client: Built-in HttpClient
• Web Automation: Selenium WebDriver (for authentication)
• Update System: Velopack

Project Structure:

• Services/ - Program services
• Services/Interfaces - Program interfaces
• Views/ - Avalonia AXAML UI views
• ViewModels/ - MVVM view models
• Assets/ - Images, icons, resources
• build_windows.py - Windows build script
• build-mac.py - macOS build script
• build-linux.py - Linux build script

Getting Started

Prerequisites

• .NET SDK - Version 6.0 or later
• Git - For cloning the repository
• IDE - Visual Studio, Rider, or VS Code with C# extensions
• Python 3.x - For build scripts

Cloning the Repository

git clone https://github.com/CyberGutta/AkademiTrack.git
cd AkademiTrack

Building the Project

Using Visual Studio / Rider

1. Open AkademiTrack.sln
2. Restore NuGet packages
3. Build → Build Solution
4. Run/Debug

Using Command Line

Windows:

dotnet restore
dotnet build
dotnet run

macOS:

dotnet restore
dotnet build
dotnet run

Linux:

dotnet restore
dotnet build
dotnet run

Build Scripts

For production builds:

Windows:

python build_windows.py

macOS:

python build-mac.py

Linux:

python build-linux.py

Build scripts handle:

• Compilation
• Packaging
• Icon management
• Creating distribution archives

Architecture

MVVM Pattern

AkademiTrack uses the MVVM (Model-View-ViewModel) pattern:

• Views (Views/) - AXAML files defining UI
• ViewModels (ViewModels/) - Logic and state management
• Models - Data structures (implicitly throughout)

Key Components

MainWindow - Primary application window

• Start/Stop automation buttons
• Activity log display
• Status updates

FeideWindow - First-time setup for Feide credentials

• School selection dropdown
• Username/password input
• Encrypted credential storage

SettingsWindow - Configuration interface

• General settings
• Automation preferences
• Update management

Core Systems

Authentication System

• Selenium-based Feide login
• Cookie management
• Credential encryption

Schedule Fetching

• iSkole API integration
• Daily schedule retrieval
• STU session identification

Conflict Detection

• Compares STU sessions with regular schedule
• Identifies overlapping time periods
• Automatically skips conflicts

Registration System

• Window timing calculation
• Automatic attendance registration
• Error handling and retries

Notification System

• Queue-based notification management
• Priority handling
• Cross-platform notifications

Update System

• Velopack integration
• Automatic update checks (every 10 minutes)
• Background downloads
• Automatic installation and restart

Logging System

• Timestamped activity logs
• Multiple log levels (INFO, WARNING, ERROR, DEBUG)
• Automatic log cleanup
• File-based persistent logging

Development Workflow

Making Changes

1. Create a branch for your feature or fix

git checkout -b feature/your-feature-name

2. Make your changes following the coding standards

3. Test thoroughly on your target platform(s)

4. Commit with clear messages

git add .
git commit -m "Add: Description of your changes"

5. Push to your fork

git push origin feature/your-feature-name

6. Create a Pull Request on GitHub

Commit Message Guidelines

Use clear, descriptive commit messages:

• Add: New feature description
• Fix: Bug fix description
• Update: Changes to existing feature
• Refactor: Code restructuring
• Docs: Documentation updates

Example:

Fix: Resolve login timeout issue on slow connections

- Increased timeout from 30s to 60s
- Added retry logic for failed requests
- Improved error messages

Testing

Manual Testing Checklist:

• Test on target platform (Windows/macOS/Linux)
• Test first-time setup flow
• Test normal automation cycle
• Test with no STU sessions
• Test with conflicting sessions
• Test settings changes
• Test update mechanism
• Test error scenarios

Platform-Specific Testing:

• Windows: Test on Windows 10 and 11
• macOS: Test on macOS 10.15+
• Linux: Test on Ubuntu and Fedora

Code Style

C# Conventions:

• Use PascalCase for classes, methods, properties
• Use camelCase for local variables, parameters
• Use meaningful variable names
• Add XML documentation comments for public APIs
• Keep methods focused and reasonably sized

Example:

/// <summary>
/// Fetches the schedule for the specified date.
/// </summary>
/// <param name="date">The date to fetch schedule for</param>
/// <returns>List of schedule sessions</returns>
public async Task<List<Session>> FetchScheduleAsync(DateTime date)
{
    // Implementation
}

AXAML/UI:

• Use proper spacing and indentation
• Group related UI elements
• Use meaningful x:Name attributes
• Comment complex layouts

Key APIs and Integrations

iSkole API

AkademiTrack interacts with iSkole's API endpoints:

Authentication:

• Uses Feide SSO via Selenium
• Captures authentication cookies
• Maintains session across requests

Schedule Endpoint:

• Fetches daily schedule data
• Returns JSON with all sessions
• Includes timing and metadata

Registration Endpoint:

• Submits attendance registration
• Requires valid session cookies
• Returns success/failure status

Important Notes:

• Respect rate limits (one schedule fetch per day)
• Handle errors gracefully
• Don't overload iSkole servers

Selenium Integration

Used for Feide authentication:

// Example structure (simplified)
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

var driver = new ChromeDriver();
driver.Navigate().GoToUrl(feideLoginUrl);
// User logs in manually
// Extract cookies after successful login
var cookies = driver.Manage().Cookies.AllCookies;

Browser drivers:

• ChromeDriver for cross-platform support
• Headless mode for background operation
• Automatic driver management

Velopack Updates

Update system integration:

// Example structure (simplified)
var updateManager = new UpdateManager(githubRepoUrl);
var updateInfo = await updateManager.CheckForUpdatesAsync();
if (updateInfo != null)
{
    await updateManager.DownloadUpdatesAsync(updateInfo);
    updateManager.ApplyUpdatesAndRestart(updateInfo);
}

Adding New Features

Example: Adding a New Setting

1. Update Settings Model

public class AppSettings
{
    public bool ExistingSetting { get; set; }
    public bool NewSetting { get; set; } // Add this
}

2. Update SettingsWindow AXAML

<CheckBox IsChecked="{Binding NewSetting}">
    New Setting Description
</CheckBox>

3. Update ViewModel

public bool NewSetting
{
    get => _settings.NewSetting;
    set
    {
        _settings.NewSetting = value;
        OnPropertyChanged();
        SaveSettings();
    }
}

4. Implement Feature Logic where needed

5. Test thoroughly

6. Update documentation (wiki pages)

Example: Adding a New API Endpoint

1. Define the endpoint in your API client class

public async Task<Response> NewEndpointAsync()
{
    var response = await _httpClient.GetAsync(endpoint);
    return await response.Content.ReadAsAsync<Response>();
}

2. Add error handling

try
{
    var result = await NewEndpointAsync();
}
catch (HttpRequestException ex)
{
    Logger.Error($"API call failed: {ex.Message}");
}

3. Test with real API

4. Document behavior

Debugging

Enable Verbose Logging

In development, enable detailed logging:

Logger.SetLevel(LogLevel.Debug);

Common Debugging Scenarios

Authentication Issues:

• Check Selenium driver output
• Verify cookie extraction
• Test with manual browser login

API Issues:

• Log full request/response
• Check HTTP status codes
• Verify endpoint URLs

UI Issues:

• Use Avalonia DevTools
• Check binding errors
• Verify AXAML syntax

Useful Debugging Tools

• Avalonia DevTools - UI inspection and debugging
• Fiddler/Postman - HTTP request inspection
• Visual Studio Debugger - Breakpoints and step-through
• Browser DevTools - Network tab for Selenium operations

Building Releases

Version Numbering

Use semantic versioning: MAJOR.MINOR.PATCH.BUILD

• MAJOR - Breaking changes
• MINOR - New features (backwards compatible)
• PATCH - Bug fixes
• BUILD - Build number (optional)

Example: 1.0.0.0 → 1.1.0.0 (new features)

Release Process

1. Update version number in project files

<Version>1.1.0.0</Version>

2. Update CHANGELOG.md with changes

3. Build for all platforms

python build_windows.py
python build-mac.py
python build-linux.py

4. Test release builds on each platform

5. Create GitHub release

• Tag: v1.1.0
• Title: v1.1.0
• Description: Copy from CHANGELOG
• Attach built files

6. Announce update (if applicable)

Build Automation Notes

Build scripts handle:

• Version string updates (with --no-automatic flag to skip)
• Icon cache clearing (Windows)
• Packaging into distributable formats
• Creating release archives

Example:

python build_windows.py --no-automatic

Contributing Guidelines

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commits
4. Test thoroughly on relevant platforms
5. Update documentation if needed
6. Submit PR with clear description

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tested on Windows
- [ ] Tested on macOS
- [ ] Tested on Linux

## Checklist
- [ ] Code follows project style
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
- [ ] All tests pass

Code Review

All PRs require review from maintainers:

• Code quality and style
• Functionality and correctness
• Platform compatibility
• Documentation completeness

Known Issues and Limitations

Current Known Issues

Linux Auto-Start Bug:

• "Start with system" doesn't work on Linux
• Investigating platform-specific implementation
• Workaround: Manual launch

Future Improvements

Potential areas for contribution:

• Mobile companion app
• Email notifications
• Advanced scheduling features
• Multiple account support
• Custom notification sounds
• Statistics and analytics

Project Dependencies

Key NuGet packages:

• Avalonia - UI framework
• Avalonia.Desktop - Desktop platform support
• Selenium.WebDriver - Browser automation
• Velopack - Update system
• Newtonsoft.Json - JSON parsing

Check AkademiTrack.csproj for complete list and versions.

Resources

Documentation

• Avalonia Docs: https://docs.avaloniaui.net/
• .NET Docs: https://docs.microsoft.com/dotnet/
• Selenium Docs: https://www.selenium.dev/documentation/

Community

• GitHub Issues - Bug reports and features
• GitHub Discussions - General questions
• Direct contact with maintainers

Related Projects

• iSkole API documentation (if available)
• Feide authentication documentation

Contact Maintainers

Project Maintainers:

• Andreas Nilsen - [@CyberNilsen](https://github.com/CyberNilsen)
• Mathias Hansen - [@CyberHansen](https://github.com/CyberHansen)

For development questions:

• Create an issue on GitHub
• Tag maintainers in discussions
• Email for private matters

License

AkademiTrack is licensed under the MIT License. See LICENSE file for details.

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Getting Started with Contributing

Ready to contribute? Here's your path:

1. Read this Development Guide thoroughly
2. Set up your development environment
3. Browse open issues for "good first issue" tags
4. Fork and clone the repository
5. Make your changes and test
6. Submit a pull request
7. Respond to review feedback

Welcome to the AkademiTrack development community! 🚀