---
title: How Thally works
description: Understand what your repository owns, how Thally publishes it, and what happens when product or framework changes need documentation updates.
url: https://pr-6-a9c4e9fe1b6c.thally.app/architecture
---

# How Thally works

Understand what your repository owns, how Thally publishes it, and what happens when product or framework changes need documentation updates.

Thally keeps your documentation in Git and adds the services needed to create,
publish, search, monitor, and update it. Your repository remains the source of
truth for pages and versioned configuration.

This guide explains the parts of the system that affect how you work with
Thally. It intentionally leaves out Thally's internal deployment topology and
service implementation.

## The system at a glance

{`
flowchart LR
    Team["Your team"] --> Docs["Documentation repository"]
    Product["Product repositories"] --> Knowledge["Product Knowledge"]
    Knowledge --> Track["Track"]
    Track --> Review["Documentation pull request"]
    Review --> Docs
    Docs --> Publish["Validation and publishing"]
    Publish --> Site["Live documentation site"]
    Site --> Readers["People and AI agents"]
`}

You interact with four parts:

| Part | What it does |
| --- | --- |
| **Your repository** | Stores pages, navigation, snippets, OpenAPI files, and versioned site defaults. |
| **Thally runtime and tools** | Render the site, validate changes, expose agent-friendly formats, and support local authoring. |
| **Thally Cloud** | Manages sites, hosting, releases, domains, analytics, Product Knowledge, Track, and workspace access. |
| **GitHub** | Provides source history, pull-request review, and the events that start publishing or Track runs. |

## What you own

Your normal authoring work stays in a small set of files:

| Path | What you control |
| --- | --- |
| `src/content/**` | Documentation pages and page metadata |
| `docs.json` | Navigation and portable feature settings |
| `src/data/site.ts` | Product identity, links, and versioned brand defaults |
| `src/mdx/custom-components.tsx` | Project-specific MDX components |
| `snippets/**` | Reusable content |
| OpenAPI files | API definitions used to generate reference pages |

Framework files are also versioned in the repository so the project remains
portable. You normally do not edit them. When Thally offers an update, it
updates framework files that still match the earlier version and leaves your
content and settings alone. If you changed a framework file yourself, Thally
names it and asks you to review that part locally instead of overwriting it.

## One source feeds every format

Thally reads each page into one structured content model. The website, search,
Markdown, JSON, JSON-LD, agent discovery files, MCP tools, and readiness checks
all use that same source.

This means a reviewed page change does not need to be copied into a separate
AI knowledge base. People and agents receive different formats of the same
published documentation.

## Managed and self-hosted sites

Choose the operating model that fits your team:

| | Managed with Thally Cloud | Self-hosted |
| --- | --- | --- |
| Source ownership | Your GitHub repository | Your GitHub repository |
| Builds and releases | Managed by Thally | Managed by your team |
| Preview deployments | Included | Configure with your host |
| Domains and certificates | Managed in Site settings | Configure with your host |
| Rollback | Select an earlier validated release | Use your host and Git history |
| Runtime updates | Guided **Update site** flow | Run the starter update locally |

A self-hosted site can still connect to Thally Cloud for supported services.
The connection does not transfer ownership of your documentation source.

## Creating and updating a site

Every supported creation path starts from the same tested Thally starter.
You can create a repository from Thally Cloud, use the CLI or MCP tools, or
migrate an existing documentation project.

For a managed site, setup follows this flow:

#### Choose the documentation source

    Create a repository or connect an existing compatible Thally project and
    production branch.

#### Connect optional product sources

    Choose the repositories whose changes Product Knowledge and Track should
    follow. You can skip this and connect them later.

#### Review and publish

    Confirm the site address and repository. Thally saves the site before
    starting setup, so retrying an interrupted setup does not create a
    duplicate.

#### Keep the framework current

    When an update is available, use **Settings → Updates**. Safe framework
    changes are committed and queued for publishing. Files needing your review
    are left untouched and listed by name.

## From product change to documentation review

Product Knowledge and Track are optional Thally Cloud services. They help your
team find documentation work without giving an AI agent permission to publish
on its own.

{`
sequenceDiagram
    participant Product as Product repository
    participant Knowledge as Product Knowledge
    participant Track as Track
    participant Docs as Documentation repository
    participant Person as Reviewer

    Product->>Knowledge: A connected product change merges
    Knowledge->>Knowledge: Compare evidence with the previous version
    Knowledge->>Track: Identify documentation that may need work
    alt No documented impact
        Track-->>Product: Finish without creating a pull request
    else Documentation may need work
        Track->>Docs: Open a draft pull request
        Person->>Docs: Review, edit, merge, or reject
    end
`}

Product sources provide the code or specifications Thally observes. The
primary documentation repository receives the main documentation pull request.
Optional Knowledge surfaces are other Markdown or MDX repositories where
Track may open a tightly scoped draft pull request.

Track never merges its own pull requests. A person decides what becomes part
of the documentation source.

## From Git commit to live release

For managed hosting, a push to the production branch creates a release
candidate. A documentation pull request receives an isolated preview.

Before a candidate becomes live, Thally checks the exact revision, validates
the project, builds what changed, and runs smoke checks. Only a successful
candidate replaces the current release. If a build or check fails, readers
continue to see the last healthy release.

Content-only changes can publish faster by reusing the already validated
runtime. Changes to application code, assets, dependencies, or uncertain files
use a full build. Both paths finish with the same validation and promotion
rules.

## Rollback and recovery

Each managed release is immutable. Rolling back selects an earlier validated
release; it does not rebuild the site or rewrite Git history.

After a rollback, automatic production publishing pauses so a delayed build
cannot immediately replace the release you restored. Resolve the source issue,
then explicitly publish again to resume automatic updates.

Temporary provider or process failures do not replace the live release.
Thally retains enough job and source information to retry supported work
without creating duplicate releases.

## Security you can rely on

- Repository access uses the installed Thally GitHub App and is scoped to the
  repositories you authorize.
- Builds and Track jobs run in isolated environments with only the access they
  need for that job.
- Product extraction reads supported source files without installing or
  executing the connected product repository.
- Workspace and site permissions are checked on every Cloud operation.
- Track opens pull requests for review and never auto-merges them.
- Failed builds, previews, or Track runs cannot replace the live production
  release.

## Choose your next guide

- [Create and manage a Cloud site](/guides/thally-cloud)
- [Publish with managed hosting](/guides/managed-hosting)
- [Set up Thally Track](/guides/thally-track)
- [Review Product Knowledge](/guides/product-knowledge)
- [Deploy the open-source runtime yourself](/guides/deploying)
- [Update a site's framework](/guides/managed-hosting#upgrade-the-site-runtime)