Repository Layout

Repository Layout

The physical folder names under src/ deliberately do not match the logical layer names used throughout the documentation and code. This page is the authoritative map between the two, plus a list of the three solutions, the build-output and package directories, and the experimental exp/ tree that is not part of the main build. Use this page as your orientation before reading any architecture or contributing page.

Contents

• Physical folder to logical layer map
• The three solutions
• Generated output and package directories
• The experimental tree
• Two reuse mechanisms in one repo
• See also

Physical folder to logical layer map

flowchart LR
    src["src/"] --> Launcher["Launcher/ → Launcher app"]
    src --> Portal["Portal/ → Portal UI"]
    src --> Live["Live/ → 8 render engines"]
    src --> Project["Project/ → Services (Backgroundog, Commandog, Watchdog, Reportdog, Property, Undo)"]
    src --> Library["Library/ → class libraries (.csproj DLLs)"]
    src --> Shared["Shared/ → Shared Item Projects (.shproj)"]
    src --> Update["Update/ → Update service"]
    src --> Bundle["Bundle/ → installer / packager"]
    src --> Localizer["Localizer/ → translation tool"]
    src --> Output["Sucrose/ → build output (generated)"]
    exp["exp/"] --> Exp["experimental ports (Avalonia, Uno, WinUI) — not in main solution"]

Loading

Physical folder	Logical layer / contents
src/Launcher/	Sucrose.Launcher — entry point, instance check, Discord Rich Presence
src/Portal/	Sucrose.Portal — the main WPF-UI settings/management UI
src/Live/	Live rendering engines: Sucrose.Live.{WebView, CefSharp, MpvPlayer, VlcPlayer, Aurora, Nebula, Vexana, Xavier}
src/Project/	The Services: Sucrose.Backgroundog, .Commandog, .Watchdog, .Reportdog, .Property, .Undo
src/Library/	Shared class libraries (.csproj, real DLLs): Manager, Memory, Mpv.NET, Pipe, Resources, Signal, Transmission, XamlAnimatedGif
src/Shared/	Shared Item Projects (.shproj + .projitems); engine-specific ones under src/Shared/Engine/
src/Update/	Sucrose.Update — auto-update service
src/Bundle/	Sucrose.Bundle — the installer/packager (separate solution src/Sucrose.Bundle.slnx)
src/Localizer/	Sucrose.Localizer — the translation tool (separate solution src/Sucrose.Localizer.slnx)
src/Sucrose/	Build output (generated; BaseOutputPath); src/Sucrose/Package holds publish packages
exp/	Experimental ports (Avalonia, Uno, WinUI, Services) — not part of the main solution

The most common navigation mistakes are looking for the services under a Services/ folder (they live in src/Project/) and looking for the shared class libraries under src/Shared/ (those are the Shared Item Projects; the class libraries are under src/Library/).

The three solutions

Solution	What it contains
src/Sucrose.slnx	The main app — all engines, services, and class libraries.
src/Sucrose.Bundle.slnx	Only the Sucrose.Bundle installer project, plus solution-items (build props/targets, packages, global.json, NuGet.Config).
src/Sucrose.Localizer.slnx	The Sucrose.Localizer translation tool.

All three use the .slnx (XML-based) solution format. See Building From Source for the restore/build commands per solution.

Generated output and package directories

BaseOutputPath is ..\..\Sucrose (resolving to src/Sucrose/). The interesting subfolders:

Path	Contents
src/Sucrose/<Layer>/<arch>/	Per-executable build output (e.g. src/Sucrose/Launcher/x64).
src/Sucrose/Live/<EngineName>/<arch>/	Per-engine build output.
src/Sucrose/Object/<Project>/	Per-project intermediate (obj) output.
src/Sucrose/Package	Publish output — dotnet publish per project lands here.
src/Sucrose/Package/Compressed/net10.0-windows/Sucrose-<arch>.7z	The compressed app payload the Bundle installer embeds.
src/Sucrose/Bundle/<arch>	The compiled installer .exe.

Everything under src/Sucrose/ is generated; do not check it in or hand-edit it.

The experimental tree

exp/ holds experimental ports of parts of Sucrose to other UI stacks (Avalonia, Uno, WinUI) and experimental services. None of exp/ is part of the main solution or the shipped product. Treat it as a sandbox; the production app is WPF only.

Two reuse mechanisms in one repo

A subtlety worth internalizing before navigating the source: Sucrose uses two distinct code-reuse mechanisms, in different folders, that must not be confused.

Mechanism	Folder	File type	How consumed	Compiled separately?
Class libraries	src/Library/	.csproj (SDK-style, OutputType=Library)	<ProjectReference Include="...csproj" />	Yes — produce their own .dll
Shared Item Projects	src/Shared/ (+ src/Shared/Engine/)	.shproj + .projitems	<Import Project="...projitems" Label="Shared" />	No — source inlined into the consumer

The Shared Item Project model is covered in depth in Shared Item Projects, and the per-executable preprocessor symbols that let one shared file compile differently per host are covered in Preprocessor Symbols.

See also

• Architecture Overview
• Shared Item Projects
• Building From Source
• Preprocessor Symbols
• Code Conventions
• Publish Pipeline