AI Documentation

The One Code's Understand module uses Claude Sonnet to read your clients' code repositories and generate comprehensive, human-readable documentation. This page explains what gets generated, how the pipeline works, how versioning works, and how to share docs with clients and auditors.

What Gets Generated

The One Code generates eight distinct document types per repository:

Doc Type	What It Covers
Architecture	High-level system design, component breakdown, technology choices, data flow between services
API	Endpoints, request/response formats, authentication, error codes, usage examples
Database	Schema overview, table/collection structure, relationships, indexing strategy, data lifecycle
Deployment	Infrastructure setup, environment variables, CI/CD pipeline, deployment steps, rollback procedure
Onboarding	Developer quickstart, local setup instructions, key concepts, first contribution guide
Data Flow	How data moves through the system, external integrations, event handling, async processing
Security	Auth mechanisms, secret management, input validation, known security considerations
Handoff	Comprehensive transfer document combining all the above, plus critical files, known issues, and suggested first tasks

Every document is written in Markdown and includes:

• Context-aware content based on actual files in the repository
• Tech stack and framework callouts specific to what was found in the code
• Version tracking — each regeneration increments the version number

How the AI Pipeline Works

When you trigger documentation generation:

1. File tree fetch — The One Code fetches the complete file tree from GitHub using the installation token
2. File selection — For each document type, a set of relevant file paths is selected (e.g., for an API doc, it reads route files, controller files, and OpenAPI specs; for a database doc, it reads migration files and schema definitions)
3. File content fetch — The selected files are fetched from GitHub
4. Context assembly — The application profile (tech stack, frameworks, languages, health scores) is combined with the file tree and file contents into a prompt context
5. AI generation — Claude Sonnet generates the document via the shared AI Gateway
6. Versioning — If a document of this type already exists for the repo, its version is incremented and the previous content is preserved in the prompt for consistency
7. Storage — The generated Markdown is stored in Cosmos DB and associated with the repo

The pipeline generates all requested document types sequentially to manage AI API throughput. For a full set of seven document types, the complete pipeline typically finishes in 3–7 minutes.

ℹ️Documentation generation requires a GitHub App installation (not just OAuth) because it reads actual file contents from the repository. You must be on the Understand tier or higher for this feature.

Triggering Documentation Generation

From the repository detail page:

1. Navigate to Portfolio and click on a repository
2. Click Generate Documentation
3. Optionally select specific document types (or leave all selected for a complete set)
4. Click Generate

The page shows a progress indicator. Each document type completes independently — you'll see them appear as they finish.

From the Docs page:

1. Navigate to Documentation from the left sidebar
2. Click Generate for Repository
3. Select the repository
4. Select document types
5. Click Generate

Viewing Documentation

The Documentation page lists all generated documents across all repositories. You can filter by:

• Repository
• Document type

Click on any document to read the full Markdown-rendered content. Documents include the generation timestamp, version number, and which AI model generated it.

Refreshing a Document

Documentation gets stale as code evolves. You can refresh any individual document on demand:

1. Open the document
2. Click Refresh (or the regenerate icon)
3. The One Code re-fetches the file tree and relevant files from GitHub and generates a new version

The version number increments. The previous content is used as context for the new generation, which helps maintain consistency in tone and structure across versions.

Background refresh is also available: go to Documentation and click Refresh All for a repository. This regenerates all documents for that repo.

Exporting Documents

Export any document as a Markdown file:

1. Open the document
2. Click Export
3. Select Markdown format
4. The file downloads as {doc-type}-{repo-id}.md

ℹ️PDF export is planned for a future release. Currently, Markdown is the only export format. To produce a PDF, open the exported Markdown in a tool like Pandoc or paste it into a Notion/Confluence page.

Sharing Documents with Clients

You can share any document as a public link without requiring the recipient to have a One Stack account. This is useful for:

• Sharing architecture docs with client technical stakeholders
• Providing onboarding documentation to new developers at a client
• Giving auditors read-only access to compliance-adjacent documentation

To create a share link:

1. Open the document
2. Click Share
3. Set the expiration period (default: 7 days)
4. Click Create Link
5. Copy the URL and share it

The recipient can view the document at app.theonecode.app/shared/docs/{token} — no login required. When the expiration date passes, the link stops working and returns an expiry notice.

💡Use longer expiration periods (30 days) for audit situations where the auditor may need to revisit the document multiple times over a few weeks.

Handoff Packages

A Handoff Package is a special documentation bundle designed for knowledge transfer — when an MSP is onboarding a new developer to a client project, when a client is taking work in-house, or when handing off a project between technicians.

A handoff package contains:

• All seven standard documentation types (architecture, API, database, deployment, onboarding, data flow, security)
• A dedicated Handoff document — a narrative transfer summary
• Critical Files — an AI-identified list of the most important files in the repo with explanations of why they matter
• Known Issues — issues the AI detected during analysis that the recipient should be aware of
• Suggested First Tasks — recommended starting points for someone new to the codebase

To generate a handoff package:

1. Navigate to Documentation → Handoff
2. Click Generate Handoff Package
3. Select the repository
4. Optionally provide the recipient's name and any context (e.g., "incoming developer, no prior experience with this stack")
5. Click Generate

The handoff package takes longer to generate than individual docs because it runs all document types plus the handoff analysis. Expect 5–10 minutes for a typical repository.

Once generated, the package shows all documents in a single view and includes the critical files and suggested task lists. You can export individual docs or share the package via link.

Documentation Versioning

Every time a document is generated or refreshed, its version number increments. Version 1 is the initial generation. The API returns the latest version — older versions are not retained in storage (only the latest version of each document type per repo is kept).

When refreshing, the previous content is passed as context to the AI, which helps maintain consistent terminology and structure across versions.

Tips for Better Results

Ensure the application profile is populated first. The AI documentation pipeline uses the application profile (tech stack, frameworks, detected app type) as context. If a profile hasn't been generated yet, the output will be less precise. Run Analyze Portfolio before generating docs.

Include relevant files. The AI reads a curated selection of files for each document type. For the best API documentation, ensure your route and controller files are present and not minified. For database docs, having migration files or ORM model files produces more accurate results than relying solely on the file tree.

Use the context field for handoff packages. Describing the recipient's background and the reason for the handoff helps the AI calibrate the language and depth of the handoff document.

Refresh after major changes. After significant refactors, dependency updates, or infrastructure changes, trigger a document refresh to keep docs in sync with the current codebase.