How it works?

This page explains UptoDocs' internal workflow and design decisions.

It is written for engineers who want to understand exactly what the system does and why.

High-Level Flow

When a relevant change occurs, UptoDocs follows this pipeline:

Code change → Analyze diff → Detect public changes → Update docs → Open PR

Each step is conservative by design.

Event Flow

1. Code Change

A developer:

• Pushes a commit
• Or merges a pull request

UptoDocs receives a GitHub webhook event.

2. Diff-Based Detection

UptoDocs analyzes the git diff, not the entire repository.

This allows it to:

• Focus only on what changed
• Avoid unrelated files
• Keep PRs small and reviewable

If the diff contains no public-facing changes, UptoDocs does nothing.

3. Public API Identification

UptoDocs attempts to identify public behavior, such as:

• Exported functions
• Public components
• API routes
• Config options

Internal utilities, tests, build files, and tooling are ignored by default.

This keeps noise low.

4. Documentation Mapping

Based on the project structure and configuration, UptoDocs determines:

• Which documentation file should be updated
• Or whether a new doc file should be created

UptoDocs respects:

• Existing documentation structure
• Framework conventions (Nextra, Fumadocs, etc.)
• User-defined paths and ignore rules

5. Pull Request Creation

If documentation updates are needed, UptoDocs opens a pull request:

• Minimal diff
• Clear commit messages
• Explanation of why the docs changed

Nothing is merged automatically.

Why Pull Requests (Not Direct Commits)

UptoDocs never pushes directly to your default branch.

Pull requests provide:

• Review and discussion
• Full transparency
• Easy rollback
• Trust

This design choice is intentional and non-negotiable.

Why There Is No Dashboard

UptoDocs is designed to live entirely inside GitHub.

Reasons:

• GitHub is already the source of truth
• Configuration via YAML is reviewable
• Comments and PRs are auditable
• No extra accounts or permissions

This reduces complexity and increases trust.

AI Usage (And Its Limits)

UptoDocs does not rely on AI for decision-making.

AI may be used for:

• Improving phrasing in documentation
• Explaining code changes in plain English
• Filling small documentation templates

AI is never used to:

• Invent features
• Decide what changed
• Rewrite large documentation sections
• Auto-merge changes

All AI output is bounded, reviewable, and optional.

Failure Modes

If UptoDocs is unsure:

• It does nothing
• Or asks for explicit confirmation via comments

Safety always wins over automation.

Summary

UptoDocs works by:

• Watching diffs, not repositories
• Updating only what changed
• Respecting existing structure
• Requiring human approval

If it feels boring, predictable, and quiet — it's working as intended.