# Core Architecture

## Summary

MatterControl is a comprehensive 3D printing workflow application built on .NET 6.0, utilizing a custom 2D/3D rendering engine (agg-sharp) with OpenGL acceleration. The architecture follows a modular design with clear separation between UI, printing infrastructure, slicing, and data persistence layers.

## Technical Description

### Overall Architecture

MatterControl employs a layered architecture consisting of:

1. **Presentation Layer** - Custom UI framework (agg-sharp/Gui) with OpenGL rendering
2. **Application Layer** - Central controller pattern via `ApplicationController`
3. **Domain Layer** - Printing, slicing, mesh operations, design tools
4. **Infrastructure Layer** - SQLite persistence, file I/O, serial communication

### Entry Point and Initialization Flow

The application entry point is `Program.cs` which orchestrates the following initialization sequence:

1. **StaticData Resolution** - Locates the `StaticData` directory containing resources (icons, fonts, profiles, translations)
2. **Culture Configuration** - Sets `CultureInfo.InvariantCulture` globally for consistent number/date formatting
3. **Serial Port Factory** - Registers platform-specific serial port implementation (`CSharpSerialPortWrapper`)
4. **Window Provider Selection** - Configures either GLFW or WinForms-based window provider
5. **Single Instance Handling** - Uses `LocalService` to ensure only one instance runs (production builds)
6. **Configuration Loading** - Loads settings from `appsettings.json` and user profile `MatterControl.json`
7. **Database Initialization** - Initializes SQLite datastore via `Datastore.Instance.Initialize()`
8. **DPI Awareness** - Configures per-monitor DPI awareness on Windows
9. **Root Window Creation** - Creates `RootSystemWindow` and displays it

### Design Rationale

**Custom Rendering Engine (agg-sharp)**: Rather than using WPF or WinForms controls directly, MatterControl uses a custom rendering abstraction. This provides:
- Cross-platform consistency (same rendering on Windows, Mac, Linux)
- Direct control over 3D viewport rendering with OpenGL
- Pixel-perfect UI scaling with `GuiWidget.DeviceScale`
- Unified input handling across platforms

**Single ApplicationController Instance**: The singleton `ApplicationController.Instance` serves as the central coordination point, managing:
- Active workspaces and printers
- Theme configuration
- Library and content providers
- Plugin registration points
- Application lifecycle events

**Workspace-Based Model**: The application uses `PartWorkspace` objects to represent open "tabs" which can be either:
- Design workspaces (standalone 3D scenes)
- Printer workspaces (associated with a specific printer)

This allows multiple concurrent editing sessions while supporting multiple connected printers.

### Module Organization

| Project | Purpose |
|---------|---------|
| `MatterControl` | Main executable, entry point, Windows-specific code |
| `MatterControlLib` | Core application logic, UI, all major features |
| `MatterControl.Printing` | GCode processing, printer communication abstractions |
| `MatterControl.OpenGL` | OpenGL rendering utilities |
| `MatterControl.MeshOperations` | Property grid and mesh editing interfaces |
| `MatterControl.SLA` | SLA/resin printer support (Photon format) |
| `MatterControl.Winforms` | WinForms window provider implementation |
| `MatterControl.Common` | Shared utilities and interfaces |
| `Community.CsharpSqlite` | SQLite database implementation |

### Key External Dependencies

- **agg-sharp**: Custom 2D graphics, UI widgets, vector math, polygon mesh operations
- **MatterSlice**: Integrated slicing engine
- **Newtonsoft.Json**: JSON serialization
- **Markdig**: Markdown rendering
- **PDFsharpNetStandard2**: PDF generation
- **Lucene.Net**: Full-text search indexing
- **Zeroconf**: Network printer discovery

### Configuration System

Configuration is loaded from multiple sources with increasing priority:
1. Built-in defaults
2. `appsettings.json` (application-level)
3. `~/MatterControl.json` (user-level)
4. Command-line arguments

The `IConfiguration` interface binds to:
- `Agg:ProviderTypes` - Window/graphics providers
- `Agg:GraphicsMode` - OpenGL configuration
- `MatterControl:Slicer:Debug` - In-process slicing for debugging
- `MatterControl:Application:EnableNetworkTraffic` - Network features toggle

## Reference

### Entry Point

| Class/Method | Location | Description |
|--------------|----------|-------------|
| `Program.Main()` | [Program.cs:83](Program.cs#L83) | Application entry point |
| `MainOutputDirectoryAttribute` | [Program.cs:326](Program.cs#L326) | Assembly attribute for build path resolution |

### Core Classes

| Class | Location | Description |
|-------|----------|-------------|
| `ApplicationController` | [MatterControlLib/ApplicationView/ApplicationController.cs](MatterControlLib/ApplicationView/ApplicationController.cs) | Central singleton managing application state |
| `RootSystemWindow` | [MatterControlLib/RootSystemWindow.cs](MatterControlLib/RootSystemWindow.cs) | Main application window |
| `MatterControlApplication` | [MatterControlLib/MatterControlApplication.cs](MatterControlLib/MatterControlApplication.cs) | Static configuration (MCWS base URI) |
| `AppContext` | [MatterControlLib/ApplicationView/AppContext.cs](MatterControlLib/ApplicationView/AppContext.cs) | Global context (theme, platform features) |

### Key Interfaces

| Interface | Purpose |
|-----------|---------|
| `INativePlatformFeatures` | Platform-specific functionality abstraction |
| `ISystemWindowProvider` | Window creation and management |
| `IStaticData` | Static resource access |

### Important Events

| Event | Publisher | Description |
|-------|-----------|-------------|
| `WorkspacesChanged` | `ApplicationController` | Fired when tabs are added/removed |
| `ApplicationError` | `ApplicationController` | Error logging hook |
| `ApplicationEvent` | `ApplicationController` | General event logging |
| `AnyPrintStarted/Canceled/Complete` | `ApplicationController` | Print lifecycle events |

### Initialization Order

```
Program.Main()
├── StaticData.OverrideRootPath()
├── CultureInfo configuration
├── FrostedSerialPortFactory setup
├── AggContext.Config.ProviderTypes
├── LocalService.TryStartServer()
├── IConfiguration loading
├── Datastore.Instance.Initialize()
├── DPI awareness setup
├── RootSystemWindow.GetStartupBounds()
├── Application.LoadRootWindow()
├── ApplicationController.Instance.Theme
└── rootSystemWindow.ShowAsSystemWindow()
```