hs-sql-agent
2.0.2
Docs 2.0.2
Documentation version
2.0.2 Latest
2.0.2 Latest
Docs Development

Architecture and Contribution Flow

A contributor-oriented map of the repository and the rules for changing compiler, server, frontend, and documentation behavior.

hs-sql-agent is split into a backend, an Admin frontend, and a separate static documentation/product site.

Repository responsibilities

At a high level:

  • backend/ contains the server, SQL compiler/runtime modules, persistence, and tests.
  • frontend/ contains the embedded Nuxt Admin Panel.
  • hs-sql-agent.site is the independent Astro product/documentation site.

The SQL compiler includes F# modules with explicit rewrite/validation stages and capability-proof concepts. Server hosting is exposed through HsSqlAgent.Server as a composable ASP.NET Core class library: new integrations start with AddHsSqlAgentCore() and select capabilities such as Runtime, AdminStore, HostAuthorization or BuiltInAuth, AdminApi, MCP, and Telemetry. AddHsSqlAgent() / UseHsSqlAgent() remain compatibility surfaces for existing consumers rather than the primary first-party integration model.

Contribution flow

The main repository contribution guide asks contributors to:

  1. Fork the repository.
  2. Implement a focused change with the required tests or documentation.
  3. Run the project locally and verify tests.
  4. Open a Pull Request with the motivation, change description, and test evidence.

Keeping one PR focused on one task makes review and merge easier.

Documentation changes

Documentation should describe the behavior of the current code rather than anticipated behavior.

When changing SQL capabilities, DML safety, MCP compatibility, hosting configuration, Admin behavior, or deployment requirements, update the relevant site page in the same workstream whenever possible.

The site uses path-based locale and documentation version content:

src/content/en/docs/<version>/<section>/<slug>.mdx
src/content/zh-hant/docs/<version>/<section>/<slug>.mdx

Both translations intentionally share the same version/section/slug and are separated by locale-prefixed routes. The current complete documentation baseline is 2.0.2.