---
title: How Thally works
description: Understand the customer-facing workflow for publishing documentation and keeping it aligned with product changes.
url: https://pr-7-a9c4e9fe1b6c.thally.app/architecture
---

# How Thally works

Understand the customer-facing workflow for publishing documentation and keeping it aligned with product changes.

Thally keeps your documentation in Git, publishes reviewed changes, and helps
your team find pages that may need an update when the product changes.

You can use the open-source documentation site by itself or connect it to
Thally Cloud for managed publishing, Product Knowledge, and Track.

## Publish from one source

Your MDX pages, navigation, assets, and configuration stay in your Git
repository. That repository remains the source your team reviews and owns.

#### Create or connect a documentation repository

    Start with a new Thally project or connect an existing compatible project.

#### Review changes in GitHub

    Authors and automation use the same branch and pull-request workflow. A
    generated update never approves or merges itself.

#### Validate before publishing

    Thally checks the documentation before a managed publish becomes live. If
    a publish fails, the current live version stays available.

#### Serve people and agents from the same content

    The reviewed source powers the website, search, Markdown, structured
    endpoints, and agent discovery files.

Managed hosting also gives each documentation pull request a preview. Owners
and editors can restore a previously successful publish from deployment
history without rewriting Git history.

## Keep documentation aligned with the product

Product Knowledge and Track add an optional review loop for teams that connect
product repositories.

```text
product change
      ↓
evidence-backed documentation matches
      ↓
proposed documentation pull request
      ↓
human review and merge
      ↓
published documentation
```

Thally reads supported product sources, records the file revision behind each
fact, and shows why a documentation page may be affected. Search can suggest a
page, but a suggestion needs supporting evidence before it reaches the review
queue.

Track uses those reviewed inputs to prepare a focused documentation pull
request for the primary docs repository or an explicitly connected Markdown
or MDX Knowledge surface. Your team can correct, merge, or close the proposal.
If no page has a supported impact, Track finishes without opening a pull
request.

## Know the ownership boundary

| You own | Thally provides |
| --- | --- |
| Documentation content and Git history | The open-source documentation site |
| Product repositories and review decisions | Validation, previews, and managed publishing |
| Hosting when you choose to self-host | Optional Product Knowledge and Track workflows |
| Whether a proposed update publishes | Evidence and a reviewable documentation proposal |

Connecting Thally Cloud does not move ownership of your documentation out of
Git. You can continue to self-host the site, and disconnecting an optional
service does not remove your authored content or history.

## Customer-facing safeguards

- Product Knowledge does not run code from a connected product repository.
- Track proposes changes through pull requests and never merges its own work.
- Pull-request previews cannot publish to production.
- A failed managed publish leaves the current site online.
- Repository access is limited to the repositories you select through the
  GitHub App installation.

## Choose your next task

- [Publish your first site](/quickstart)
- [Manage sites with Thally Cloud](/guides/thally-cloud)
- [Review Product Knowledge](/guides/product-knowledge)
- [Set up Thally Track](/guides/thally-track)
- [Operate managed hosting](/guides/managed-hosting)