> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/documentation/en/overview/architecture.md). # Architecture Overview Understand the responsibilities of Core, plugins, hosts and infrastructure from the perspective of dependency direction and running process. To understand Zongsoft, you can first observe along a business request: the web host receives the request, the business plugin processes the use case, obtains the data accessor, cache or message queue through the public interface, and the specific plugin then accesses the database and external systems. The host provides the running environment, the business expresses the intention, and the implementation plugin is responsible for the technical details. ## Dependency Direction ```mermaid flowchart BT Business["Business plugin"] --> Core["Core public contract"] Data["Data and database drivers"] --> Core Adapters["Message and third-party adaptation"] --> Core Plugins["Plugins assembly runtime"] --> Core Web[Plugins.Web] --> Plugins Web --> WebBase["Web Basics"] Host["Terminal/Backend/Web Host"] --> Plugins ``` The arrows show the main dependency direction, with some project references omitted. This differs from runtime call order: business code can use a Redis cache at runtime while referencing only the [Core](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Core) caching contract at compile time. [Deployment](/documentation/en/overview/deployment.md) and [Service Resolution](/documentation/en/framework/core/services.md) connect the contract to its implementation. ### Core: a Stable Common Language [Core Library](/documentation/en/framework/core.md) includes public contracts such as applications and modules, services, data access, messaging, file systems, security, and configuration, as well as common implementations such as collections and conversions. Which interface the business relies on should be determined by the ability to express, not by the database or SDK to be adopted. This does not mean that all capabilities have exactly the same semantics. For example, multiple message plugins implement the same interface, but there are still differences in message confirmation, persistence and sequence. For details, see [Message basic concepts](/documentation/en/framework/messaging/concepts.md). ### Plugins: Turn Declarations Into Running Objects [Plugin Framework](/documentation/en/framework/plugins.md) reads the plugin manifest, resolves dependencies, organizes [plugin tree](/documentation/en/overview/concepts.md#plugin-tree), loads the declared assembly and registers the service. Builtins on the plugin tree can be created by builders or expose existing instances. File directories organize deployment files and plugin parent-child relationships; extension paths such as `/Workbench/Modules` organize runtime objects. The two levels serve file deployment and object composition respectively; they are entirely different organizational structures. ### Function Libraries and Adapters: Realizing Replaceable Capabilities [Data Engine](/documentation/en/framework/data.md) is responsible for mapping, query expressions and execution pipeline, and the database driver is responsible for the dialect and database client. Libraries such as [Web](/documentation/en/framework/web.md), [Security](/documentation/en/framework/security.md), and [Diagnostics](/documentation/en/framework/diagnostics.md) provide implementations for specific fields. [external extension](/documentation/en/framework/externals.md) is responsible for integrating third-party infrastructure. The prerequisite for replacement is that both parties meet the same business semantics. After changing the driver name, you still need to verify the data type, query function, transaction and deployment dependencies; after changing the script engine, you still need to verify the script language. ## From Files to Applications ```mermaid flowchart LR Build["Compile reference"] --> Publish["publish host"] Manifest[".deploy combination solution"] --> Deploy["Deploy plugins and resources"] Publish --> Runtime["Start the host"] Deploy --> Runtime Runtime --> Load[".plugin dependencies and assembly"] Load --> Config[".option configuration and service registration"] Config --> Workbench["application context and workbench"] Workbench --> Invoke["Commands/API/Background workers"] ``` 1. **Compilation** checks that code can call the target API. Debug references in the framework source may also depend on local [Core](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Core) build output. 2. **Deployment** copies manifests, assemblies, options, mappings, and supporting resources into a complete runtime directory. 3. **Startup** establishes the content root, configuration, and container, loads plugins, and initializes the application. 4. **Invocation** triggers the creation of some lazy services, drivers, and external connections. {% hint style="info" %} 💡 The presence of a plugin in the list only proves that it has been discovered or loaded. Verifying a functionality also requires checking service resolution, valid configuration, and first business invocation. {% endhint %} ## Who Manages the Lifecycle? The application context connects the start and stop of the host, and the [workbench](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins/src/IWorkbenchBase.cs) hosts the components that need to be run. Ordinary services and startable [workers](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Components/IWorker.cs) have different responsibilities: services provide operations; workers are responsible for continuous running, cancellation and closing. The constructor should try to only establish the object state and avoid putting uncontrollable external work into the assembly phase. The module service container provides name scope and fallback rules that are not scoped per HTTP request. Shared services cannot save mutable state that is exclusive to a request, and the caller should not release shared instances obtained from the container at will. See [Modules, services and providers](/documentation/en/overview/concepts.md#module-service-provider) for details. ## Choose a Reading Path * New application: from [Prerequisites](/documentation/en/get-started/prerequisites.md) to [Deploy Your First Plugin](/documentation/en/get-started/deploy-first-plugin.md). * Develop composable services: first look at [basic concepts](/documentation/en/overview/concepts.md), then [Plugin Application Model](/documentation/en/framework/plugins/application-model.md). * Integration database: first understand [Object Relationships and Data Access](/documentation/en/framework/data/concepts.md), and then complete mapping, connection and query. * Operation and maintenance delivery: From [Deployment Model](/documentation/en/overview/deployment.md) to [Host deployment](/documentation/en/hosting/deployment.md) and [Tools](/documentation/en/tools/tools.md). Source references: [Core](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Core/src), [Application builder](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins/src/Hosting/ApplicationBuilder.cs), [Web plugin entrance](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins.Web/src/Application.cs). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.zongsoft.com/documentation/en/overview/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.