Advanced

Contributing

How to contribute to Segra - development setup, guidelines, and workflow

Segra is an open-source project, and we welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, this guide will help you get started.

Before You Start

Segra is built with C#/.NET for the backend and React/TypeScript for the frontend. Familiarity with these technologies is helpful but not required for all contributions.

Ways to Contribute

Report Bugs

Found an issue? Report it on GitHub Issues

Suggest Features

Have an idea? Open a feature request on GitHub

Fix Issues

Browse open issues and submit pull requests

Improve Docs

Help us improve guides and documentation

Development Setup

Requirements

Windows 10 (build 19041 / 20H1) or newer
.NET SDK 10.0.x with Windows targeting
Git for version control
Bun v1.1+ for frontend tooling and git hooks

Repository Structure

Segra/
├── Segra.sln              # Solution file
├── Segra.csproj           # Main project file
├── Backend/               # C# backend code
│   ├── Api/              # Local HTTP content server (/api/content, /api/thumbnail)
│   ├── App/              # Application services (Program, MessageService, UpdateService, ...)
│   ├── Core/             # Core models and types
│   ├── Games/            # Game integrations
│   ├── Media/            # Video/audio processing
│   ├── Recorder/         # OBS integration
│   ├── Services/         # Backend services
│   ├── Shared/           # Cross-cutting helpers (PathUtils, FolderNames, GeneralUtils)
│   └── Windows/          # Windows-specific code
├── Frontend/              # React frontend
│   ├── src/
│   ├── package.json
│   └── vite.config.ts
└── .husky/               # Git hooks

First-Time Setup

Clone the Repository

git clone https://github.com/Segergren/Segra.git
cd Segra

Or clone your fork if you're contributing:

git clone https://github.com/YOUR_USERNAME/Segra.git

Install Root Dev Tools

Install Husky and lint-staged for git hooks:

bun install
bun run prepare

Install Frontend Dependencies

cd Frontend
bun install
cd ..

Verify .NET SDK

Ensure .NET SDK 10 is installed:

dotnet --info

Should show Version: 10.x and OS: Windows

Development Workflow

Running the Application

Segra has two parts that run during development:

The frontend dev server runs on http://localhost:2882:

Using Bun (recommended):

cd Frontend
bun run dev

Using Node/npm:

cd Frontend
npm run dev

From the repository root:

dotnet run --project Segra.csproj

In Debug mode, the backend expects the frontend on http://localhost:2882. If Node/npm is installed, it will automatically run npm run dev if nothing is listening on port 2882.

Making Changes

Create a Branch

git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring

Make Your Changes

Edit code in your preferred IDE:

Visual Studio 2022: Open Segra.sln
VS Code: Open folder, install C# Dev Kit extension

Hot reload is supported for frontend (Vite) and backend (.NET 10).

Test Your Changes

Manual testing: Run the application and verify functionality
Check the log file at %AppData%/Segra/logs.log for errors
Test on a clean Windows installation if possible

Commit Your Changes

Git hooks will automatically run:

Pre-commit: Formats C# code with dotnet format, runs Prettier/ESLint on frontend
Pre-push: Verifies no formatting drift in solution

git add .
git commit -m "feat: add new feature"

Commit message format:

feat: - New feature
fix: - Bug fix
docs: - Documentation
refactor: - Code refactoring
perf: - Performance improvement
test: - Test changes

Code Style and Formatting

Code formatting is enforced automatically via EditorConfig and git hooks.

EditorConfig Settings

Global (all files):

Line endings: CRLF
Indent: 2 spaces

C# files:

Line endings: CRLF
Indent: 4 spaces

C# Formatting

Formatting is handled by dotnet format:

Formats staged *.cs files automatically before commit

Runs dotnet format --verify-no-changes on entire solution

# Format entire solution
dotnet format

# Format specific project
dotnet format Segra.csproj

Frontend Formatting

The frontend uses Prettier + ESLint with Bun:

cd Frontend

# Check formatting
bun run format:check

# Auto-fix formatting
bun run format

# Check linting
bun run lint

# Auto-fix linting
bun run lint:fix

Building for Release

Backend Build

# Debug build
dotnet build -c Debug

# Release build
dotnet build -c Release

# Publish (self-contained)
dotnet publish -c Release

Builds made outside GitHub Actions define the LOCAL_BUILD constant. Local builds skip the auto-updater and the hotkey broker.

Frontend Build

cd Frontend
bun run build

This creates optimized production files in Frontend/dist/.

Key Architecture Concepts

Backend Architecture

OBSService - Recording Engine

Located in Backend/Recorder/OBSService.cs

Responsibilities:

OBS context initialization
Scene and source management
Encoder configuration
Recording/replay buffer outputs

Key Methods:

InitializeAsync() - Initialize OBS
StartRecording() - Start recording session
StopRecording() - Stop and cleanup
SaveReplayBuffer() - Save replay buffer

GameDetectionService

Located in Backend/Games/GameDetectionService.cs

Responsibilities:

Monitor Windows processes
Detect game launches
Auto-start recording

Uses WMI event watchers for process monitoring.

SettingsService

Located in Backend/Core/SettingsService.cs

Responsibilities:

Load/save user settings
Content folder management
Display/audio device enumeration

ContentService

Located in Backend/Media/ContentService.cs

Responsibilities:

Metadata file creation
Thumbnail generation
Waveform generation
Content library management

Frontend Architecture

The frontend is built with:

React 19 - UI framework
TypeScript - Type safety
Vite - Build tool and dev server
Tailwind CSS - Styling
DaisyUI - Component library

Communication with backend uses:

WebSockets for real-time updates. The server runs at ws://localhost:44030/.
A local content HTTP server at http://localhost:2222/ exposing /api/content and /api/thumbnail.
Per-game local listeners such as the Counter-Strike 2 GSI endpoint at http://127.0.0.1:1340/ and the Dota 2 GSI endpoint at http://127.0.0.1:1341/.
IPC for PhotinoX integration.

Common Development Tasks

Adding a New OBS Source Type

Add Source Creation

In OBSService.cs, create the source:

var customSource = new Source("source_id", "Source Name");
customSource.Update(s => {
    s.Set("property", value);
});

Add to Scene

var sceneItem = _mainScene.AddSource(customSource);

Cleanup on Stop

Add disposal in DisposeSources() method

Adding a New Game Integration

Create Integration Class

Create new file in Backend/Games/YourGame/YourGameIntegration.cs:

public class YourGameIntegration : Integration
{
    // Implementation
}

Implement Integration Logic

Override methods from Integration base class for event detection

Add your integration to the service initialization

Adding a New Setting

Add Property to Settings Model

In Backend/Core/Models/Settings.cs:

[JsonPropertyName("yourSetting")]
public bool YourSetting
{
    get => _yourSetting;
    set
    {
        _yourSetting = value;
        SendToFrontend("YourSetting changed");
    }
}

Add UI in Frontend

Create settings component in Frontend/src/components/Settings/

Wire Up Setting

Connect frontend UI to backend setting via IPC

Debugging

Backend Debugging

Open Segra.sln
Set breakpoints in code
Press F5 to start debugging
Debugger attaches automatically

Check application logs:

Location: %AppData%/Segra/logs.log (single self-trimming file capped at 10 MB)
Use Serilog for logging:

Log.Information("Message");
Log.Warning("Warning message");
Log.Error("Error message");

Frontend Debugging

Browser DevTools: Inspect elements, console, network
React DevTools: Install browser extension for component inspection
Vite HMR: Hot Module Replacement for instant feedback

Git Hooks

Segra uses Husky + lint-staged for automated code quality:

Runs on git commit:

Formats staged *.cs files with dotnet format
Runs Prettier on frontend staged files
Runs ESLint on frontend staged files

Runs on git push:

Verifies no formatting drift: dotnet format --verify-no-changes
Prevents pushing unformatted code

If hooks don't run, ensure Bun is on PATH in your Git shell:

bun install
bun run prepare

Pull Request Guidelines

Before Submitting

Keep PRs Focused

One feature or fix per PR
Small, reviewable changes
Avoid mixing refactoring with features

Run Format and Lint

# Backend
dotnet format

# Frontend
cd Frontend
bun run format
bun run lint:fix

Test Thoroughly

Test your changes manually
Verify no regressions in existing features
Include steps to reproduce in PR description

Update Documentation

If your change affects user-facing features, update docs

PR Description Template

## Description
Brief description of changes

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

## Testing
- How were these changes tested?
- What edge cases were considered?

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Code follows project style
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] No console errors/warnings

Community

GitHub Discussions

Ask questions and discuss ideas

Issues

Report bugs and request features

Discord

Join the community chat

Twitter

Follow for updates

Code of Conduct

Segra follows the Contributor Covenant Code of Conduct. Be respectful, inclusive, and collaborative.

License

By contributing to Segra, you agree that your contributions will be licensed under the GPLv2 License.

Segra is licensed under GPLv2, which means:

You can use, modify, and distribute the software
Modifications must also be GPLv2
Source code must be made available

Getting Help

If you need help contributing:

Check existing documentation and guides
Search GitHub Issues for similar questions
Ask in GitHub Discussions
Join the Discord community

Thank you for contributing to Segra!