# Product Architecture

> Core and Classic engines, ServerTextControl and MailMerge in your process, the Document Editor WebSocket and TCP backend, the Document Viewer and scaling out.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Overview > Product Architecture
- **3019 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/architecture/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/architecture/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/architecture/llms-full.txt

---

Knowing how the parts of TX Text Control .NET Server run and connect makes it easier to plan a project or a deployment. The parts are the document engine, the components that run inside your application and the browser components with the backends they need. Together, they determine which packages you install, which processes your application starts and which network connections it uses.

### Architecture at a Glance

TX Text Control .NET Server has three layers:

- **The document engine** loads, lays out, renders and saves documents. You choose between the Core and the Classic engine.
- **The server-side components** `ServerTextControl` and `MailMerge` are .NET classes that you use in your own code. They run inside your application's process.
- **The browser components**, the Document Editor and the Document Viewer, consist of a frontend in the browser and a backend in your ASP.NET Core application. The Document Editor also uses a separate backend process.

The following diagram shows all parts in one ASP.NET Core application:

```text
Browser                            Your ASP.NET Core application      Separate process

Document Editor  ---WebSocket--->  WebSocketMiddleware  -----TCP--->  TXTextControl.Web.Server.Core

Document Viewer  ------HTTP----->  Document Viewer backend
                                   ServerTextControl and MailMerge
                                   TX Text Control engine
```

The following sections describe each part from the bottom up.

### The Document Engine

The engine is the part of TX Text Control that every other component uses. It consists of .NET assemblies and native libraries for each supported platform. TX Text Control .NET Server ships with two engines, each in its own NuGet package.

#### Core and Classic

|  | Core | Classic |
|---|---|---|
| NuGet package | `TXTextControl.TextControl.Core.SDK` | `TXTextControl.TextControl.ASP.SDK` |
| Operating systems | Windows and Linux, including Linux containers such as Docker and Kubernetes | Windows only |
| Native runtimes in the package | `win-x64` and `linux-x64` | `win-x64` and `win-x86` |
| .NET | .NET 8 or higher | .NET 8 or higher. ASP.NET applications on the .NET Framework 4.x use the Classic engine from the Windows setup instead of the NuGet package. |
| Rendering | SVG-based rendering engine developed by Text Control, no dependency on GDI | GDI-based |
| Fonts | Its own font rendering with a *Fonts* folder that is deployed with your application | Fonts installed on the Windows system |
| DOC (legacy Word binary format) | Not supported | Supported |
| Document Viewer package | `TXTextControl.Web.DocumentViewer` | `TXTextControl.Web.DocumentViewer.Classic` |
| Available since | Version 33.0 | The original TX Text Control engine |

Both packages target .NET 8 and support .NET 8, .NET 9 and .NET 10. They provide nearly the same functionality, and both contain the `ServerTextControl` class in the `TXTextControl` namespace, so your code looks the same with either engine.

Which engine to choose:

- **Core** is recommended for new .NET 8 or higher projects and for applications that you migrate to .NET 8 or higher. It is required for Linux and Linux containers.
- **Classic** is for Windows-only applications, existing Classic integrations, and applications that must load or save DOC or XML files.

The blog article [TX Text Control Classic vs Core - When to use which Version](https://www.textcontrol.com/blog/2025/07/16/tx-text-control-classic-vs-core-when-to-use-which-version/) explains the differences in more detail. [Core and Classic Differences](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/file-formats/#core-and-classic-differences) lists all format differences, such as XML, RTF and EMF, and [From Classic to Core](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/previous-versions/#from-classic-to-core) moves an existing application to the Core engine.

#### Fonts in the Core Engine

The Classic engine uses the fonts installed on Windows. The Core engine does not depend on GDI or system fonts. Its package adds a *Fonts* folder with a standard set of serif and sans-serif fonts to your project and copies it to the output directory. To use other fonts, add them to this folder when you deploy your application.

Because the fonts are deployed with the application, documents render the same way in every environment. This matters in Docker containers and Azure App Services, where installing system fonts is difficult.

### ServerTextControl and MailMerge

`ServerTextControl` is the non-visual document processing component. It has no window and no user interface. You create an instance in your code, load or build a document through its properties and methods, and save the result.

`MailMerge` in the `TXTextControl.DocumentServer` namespace merges data into templates. It uses a `ServerTextControl` to hold the template and the merged document: you load the template into a `ServerTextControl` and connect `MailMerge` to it through the `TextComponent` property.

Both classes are part of the engine package, and they run in the process of your application:

- They do not need a separate service, backend process or network connection.
- You can use them in any .NET application that runs on the server or in the background, such as ASP.NET Core applications, Web APIs, console applications and services.
- Document processing uses the CPU and memory of your application's process. Large jobs, such as batch mail merges or PDF generation, therefore compete with everything else that runs in the same instance. [Scaling Beyond One Instance](#scaling-beyond-one-instance) describes how to separate them.

The `TXTextControl.DocumentServer.ParallelMailMerge` package on nuget.org runs `MailMerge` processing in isolated worker processes.

### Document Editor

The Document Editor is not a pure client-side component. The frontend in the browser shows the ribbon, the pages and the text, but the document itself is synchronized with the server. The server calculates the rendering information for the editor, which is how the browser shows a true WYSIWYG view of the document.

The connection chain has three parts:

```text
Document Editor frontend (browser)
        |
        |  WebSocket, for example wss://localhost:7118/api/TXWebSocket
        v
WebSocketMiddleware (your ASP.NET Core application, package TXTextControl.Web)
        |
        |  TCP, port 4283 by default
        v
TXTextControl.Web.Server.Core (backend process, package TXTextControl.Web.DocumentEditor.Backend)
```

1. **The frontend** runs in the browser. It opens a WebSocket connection to your ASP.NET Core application and exchanges every change with the server over this connection.
2. **The WebSocket middleware** runs in your ASP.NET Core application. You enable WebSockets with `app.UseWebSockets()` and add the middleware with `app.UseTXWebSocketMiddleware()`. The middleware accepts the WebSocket connections of the editors and forwards them to the backend process over TCP. For plain JavaScript pages, it also serves the editor script *tx-document-editor.min.js*.
3. **The backend process** `TXTextControl.Web.Server.Core` is a .NET application that runs on Windows and Linux. It synchronizes the documents, keeps the live state of every open document and performs layout calculations for the editor. It uses the Core engine, so an application that hosts it also installs `TXTextControl.TextControl.Core.SDK`.

The `TXTextControl.Web.DocumentEditor.Backend` package contains the files of the backend process and copies them to the build and publish output. Its hosted service `DocumentEditorWorkerManager` starts the process when your application starts, forwards its output to the ASP.NET Core logging, and stops it when your application shuts down. You register it with `builder.Services.AddHostedService<DocumentEditorWorkerManager>()`.

Running the backend in its own process isolates the editing sessions from your web application, and both can be scaled separately. In version 32.0 and earlier, this backend was a Windows service, which older articles call the TCP synchronization service. In ASP.NET Core applications, version 33.0 replaced it with the cross-platform `TXTextControl.Web.Server.Core` application; ASP.NET applications on the .NET Framework deploy the Windows service, also in 34.0. Some articles written for version 33.0 copy its files from the setup folder and start the process with their own code. The backend package replaces these manual steps.

#### Where the Backend Process Runs

By default, `DocumentEditorWorkerManager` starts the backend process on the same machine, and `app.UseTXWebSocketMiddleware()` without parameters connects to it. The backend can also listen on another address and port, or run on its own machine or in its own container; the middleware then needs the same address and port. [Configure the Backend Process](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/architecture/#configure-the-backend-process) in the Document Editor section describes both configuration files and the separate setup.

### Document Viewer

The Document Viewer uses HTTP requests instead of a WebSocket connection, and it does not need the Document Editor backend process. Your ASP.NET Core application loads the document and renders its pages with the TX Text Control engine.

```text
Document Viewer frontend (browser)
        |
        |  HTTP requests to the TextControl controller
        v
Document Viewer backend (your ASP.NET Core application, package TXTextControl.Web.DocumentViewer)
        |
        |  in the same process
        v
TX Text Control engine (Core or Classic package)
```

- **The frontend** is a web component with the element name `tx-document-viewer`. It requests the pages from the backend and displays them. The backend sends pages as soon as they are rendered, so users can start reading a large document before all pages are ready.
- **The backend** is a controller named `TextControl` that the `TXTextControl.Web.DocumentViewer` package adds to your ASP.NET Core application. In an ASP.NET Core MVC application, the template's controller routing is enough. Applications without MVC views, such as Web API backends, add the viewer with `app.UseTXDocumentViewer()`.
- **The engine** renders the pages as bitmaps, as vector graphics (SVG) or with the actual fonts. By default, the viewer chooses the mode automatically.

The viewer package depends on the engine you use: `TXTextControl.Web.DocumentViewer` works with the Core package, `TXTextControl.Web.DocumentViewer.Classic` with the Classic package, as the table in [The Document Engine](#the-document-engine) shows.

When a user signs a document in the viewer, your backend receives the signed document and can digitally sign it with a certificate.

### Frontends and the ASP.NET Core Backend

Every Document Editor and Document Viewer frontend needs an ASP.NET Core backend with TX Text Control .NET Server. The frontend either lives in the same application as the backend or is a separate client application.

| Frontend | Document Editor | Document Viewer | Relation to the backend |
|---|---|---|---|
| ASP.NET Core MVC | `Html.TXTextControl().TextControl()` HTML helper from `TXTextControl.Web` | `Html.TXTextControl().DocumentViewer()` HTML helper from `TXTextControl.Web.DocumentViewer` | Same application |
| Blazor | `DocumentEditor` component from `TXTextControl.Web.Blazor.DocumentEditor` | `DocumentViewer` component from `TXTextControl.Web.Blazor.DocumentViewer` | Same application, a Blazor Web App with interactive server rendering |
| Angular | `@txtextcontrol/tx-ng-document-editor` npm package | `@txtextcontrol/tx-ng-document-viewer` npm package | Separate client application |
| React | `@txtextcontrol/tx-react-document-editor` npm package | `@txtextcontrol/tx-react-document-viewer` npm package | Separate client application |
| JavaScript | Script loaded from the backend, started with `TXTextControl.init()` | Scripts loaded from the backend, `tx-document-viewer` element | Separate HTML page |

The Blazor components are installed from nuget.org. In the same application, the frontend needs no connection settings. A separate client application needs the address of the backend:

- **Document Editor:** the `webSocketURL` setting contains the backend address with the `wss` protocol and the path `/api/TXWebSocket`, for example `wss://localhost:7118/api/TXWebSocket`. Use `ws` when the backend runs on HTTP. The Document Editor needs no CORS policy.
- **Document Viewer:** the `basePath` setting contains the URL of the backend, for example `https://localhost:7275`. Because the client application and the backend run on different origins, the backend must allow cross-origin requests (CORS).

All Document Editor frontends use the same JavaScript API, the [TXTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/llms-full.txt) object. The ASP.NET Core, Angular, React and JavaScript frontends of the Document Viewer share the [TXDocumentViewer](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript-document-viewer/txdocumentviewer/llms-full.txt) object. What you learn in one frontend applies to the others.

### Scaling Beyond One Instance

In development and in smaller deployments, all parts run in one instance: the WebSocket middleware, the Document Editor backend process, the Document Viewer and your document processing code with `ServerTextControl` and `MailMerge`. When the number of concurrent users grows, Text Control recommends three services that scale on their own: application instances with the WebSocket middleware, the `TXTextControl.Web.Server.Core` backend, and a separate document processing application. Because a Document Editor session is tied to the backend instance that holds its live document, a load balancer needs sticky sessions. [Container Scaling](https://docs.textcontrol.com/tx-text-control-dotnet-server/performance/container-scaling/#three-workloads-three-measures) describes the three workloads and their sizing.

### Next Steps

- [Components](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/components/llms-full.txt): what each component does, with its packages and key classes.
- [Supported Platforms](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/platforms/llms-full.txt): operating systems, .NET versions, containers and cloud platforms for Core and Classic.
- [Document Editor](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/llms-full.txt) in Getting Started: set up the connection chain in your first application.
- [Deployment Guide](https://docs.textcontrol.com/tx-text-control-dotnet-server/deployment/llms-full.txt): run the application and the backend process on Windows, Linux, Docker and in the cloud.

---

## Nearby

- **Previous:** [Introduction](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/introduction/llms-full.txt)
- **Next:** [Components](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/components/llms-full.txt)