# langchain-ai/openwiki architecture

> Architecture diagram of the GitHub repository langchain-ai/openwiki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/openwiki
- Repository: https://github.com/langchain-ai/openwiki

## Overview

1. **What this repo is**
   OpenWiki is a TypeScript/Node.js CLI for generating and continuously maintaining a repository’s documentation. It is not a web app; the main runtime is a terminal command that reads the current codebase, writes docs into an `openwiki/` workspace, and can be run interactively or as a one-shot command.

2. **Top-level execution path**
   The main entrypoint is `src/cli.tsx`, which parses the CLI flags and dispatches into `src/commands.ts`. From there, the tool branches into the main user flows: initialize a wiki, generate/update docs, or open an interactive agent session.

3. **Command boundary**
   `src/commands.ts` is the orchestration layer. It likely owns the distinction between:
   - first-time setup (`--init`)
   - documentation refresh (`--update`)
   - interactive mode vs print/non-interactive mode  
   This is the boundary where user intent becomes repository changes.

4. **Agent subsystem**
   The core documentation-writing logic lives under `src/agent/`:
   - `index.ts` likely drives the agent loop
   - `prompt.ts` defines the system/task prompting
   - `types.ts` defines agent-facing data structures
   - `utils.ts` contains supporting logic  
   This subsystem is responsible for deciding what docs to create/update and how to phrase them for the LLM.

5. **Configuration and credentials**
   `src/env.ts` and `src/credentials.tsx` indicate a dedicated setup layer for provider selection, API keys, and local persistence. The README says these settings are stored in `~/.openwiki/.env`, which makes configuration a local-machine concern rather than a repo concern.

6. **Documentation workspace as an output boundary**
   The `openwiki/` directory is the generated/maintained documentation tree. It contains domain-specific docs such as:
   - `openwiki/architecture/overview.md`
   - `openwiki/cli/usage.md`
   - `openwiki/operations/credentials-and-updates.md`
   - `openwiki/agent/workflow.md`
   - `openwiki/quickstart.md`  
   This folder is the main artifact the agent writes to and refreshes over time.

7. **State and update tracking**
   `openwiki/.last-update.json` suggests the tool tracks the last successful generation/update checkpoint. That file is likely used to determine what changed since the previous run and to make updates incremental rather than rewriting everything blindly.

8. **Repository onboarding integration**
   The README says OpenWiki appends guidance to `AGENTS.md` and/or `CLAUDE.md`, and will create those files if missing. That means the tool also mutates repository-adjacent agent instructions so future coding agents know to consult OpenWiki docs when searching for context.

9. **External services**
   The only external runtime dependencies that materially affect architecture are:
   - LLM/inference providers: OpenRouter, Fireworks, Baseten, OpenAI, Anthropic
   - Optional LangSmith tracing for OpenWiki runs  
   The model/provider selection is part of the CLI setup, and it changes how the agent subsystem is executed, but not the repo’s document layout.

10. **Automation / maintenance loop**
   `.github/workflows/openwiki-update.yml` and the example under `examples/` define the scheduled maintenance path. The repository is designed so a GitHub Action can run OpenWiki on a cadence and open a PR with documentation updates, making the docs pipeline continuous rather than manual.

11. **Validation and developer tooling**
   `.github/workflows/checks.yml`, `eslint.config.js`, `tsconfig.json`, `pnpm-lock.yaml`, and the package scripts together show a standard TypeScript CLI project with CI validation. These support the code that drives the agent and command layers, but are not part of the runtime doc-generation pipeline.

12. **Architectural flow to diagram**
   A good diagram should show:
   - user/CI invoking the CLI
   - CLI command parsing
   - config/credential loading
   - agent prompting and LLM provider call
   - file-system writes to `openwiki/`
   - optional updates to `AGENTS.md` / `CLAUDE.md`
   - optional GitHub Action loop that re-runs generation and opens a PR  
   The key architectural boundary is between “CLI/orchestration” and “LLM-driven documentation generation,” with the repository filesystem as the shared artifact store.

Main entry points: [`src/commands.ts`](https://github.com/langchain-ai/openwiki/blob/main/src/commands.ts) (Commands), [`src/agent/index.ts`](https://github.com/langchain-ai/openwiki/blob/main/src/agent/index.ts) (Agent loop), [`openwiki`](https://github.com/langchain-ai/openwiki/tree/main/openwiki) (OpenWiki docs), [`.github/workflows/checks.yml`](https://github.com/langchain-ai/openwiki/blob/main/.github/workflows/checks.yml) (Checks workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_node_cli["CLI entry<br/>ts entrypoint<br/>[cli.tsx]"]
  node_node_commands["Commands<br/>orchestrator<br/>[commands.ts]"]
  node_node_agent["Agent loop<br/>doc agent<br/>[index.ts]"]
  node_node_prompt["Prompting<br/>prompt spec<br/>[prompt.ts]"]
  node_node_agent_types["Agent types<br/>data types<br/>[types.ts]"]
  node_node_agent_utils["Agent utils<br/>helpers<br/>[utils.ts]"]
end

subgraph group_group_state["State & config"]
  node_node_env["Environment<br/>config loader<br/>[env.ts]"]
  node_node_credentials["Credentials<br/>local setup<br/>[credentials.tsx]"]
  node_node_constants["Constants<br/>shared config<br/>[constants.ts]"]
end

subgraph group_group_workspace["Documentation workspace"]
  node_node_wiki[("OpenWiki docs<br/>generated workspace")]
  node_node_update_state["Last update<br/>checkpoint<br/>[.last-update.json]"]
  node_node_agents_md["Agent guides<br/>repo instructions<br/>[AGENTS.md]"]
  node_node_claude_md["Claude guide<br/>repo instructions<br/>[CLAUDE.md]"]
end

subgraph group_group_automation["Automation"]
  node_node_github_update["Update workflow<br/>github action"]
  node_node_examples["Example workflow<br/>example config"]
end

subgraph group_group_tooling["Tooling"]
  node_node_checks["Checks workflow<br/>ci workflow<br/>[checks.yml]"]
  node_node_package["Package scripts<br/>node project<br/>[package.json]"]
  node_node_eslint["ESLint config<br/>[eslint.config.js]"]
  node_node_tsconfig["TS config<br/>build config<br/>[tsconfig.json]"]
end

node_node_cli -->|"dispatches"| node_node_commands
node_node_commands -->|"loads"| node_node_env
node_node_commands -->|"sets up"| node_node_credentials
node_node_commands -->|"runs"| node_node_agent
node_node_commands -->|"writes"| node_node_wiki
node_node_commands -->|"tracks"| node_node_update_state
node_node_agent -->|"uses"| node_node_prompt
node_node_agent -->|"structures"| node_node_agent_types
node_node_agent -->|"depends on"| node_node_agent_utils
node_node_env -->|"shares"| node_node_constants
node_node_credentials -->|"updates docs"| node_node_wiki
node_node_wiki -->|"references"| node_node_agents_md
node_node_wiki -->|"references"| node_node_claude_md
node_node_github_update -->|"invokes"| node_node_cli
node_node_examples -.->|"mirrors"| node_node_github_update
node_node_checks -->|"validates"| node_node_package
node_node_checks -->|"uses"| node_node_eslint
node_node_checks -->|"uses"| node_node_tsconfig

click node_node_cli "https://github.com/langchain-ai/openwiki/blob/main/src/cli.tsx"
click node_node_commands "https://github.com/langchain-ai/openwiki/blob/main/src/commands.ts"
click node_node_agent "https://github.com/langchain-ai/openwiki/blob/main/src/agent/index.ts"
click node_node_prompt "https://github.com/langchain-ai/openwiki/blob/main/src/agent/prompt.ts"
click node_node_agent_types "https://github.com/langchain-ai/openwiki/blob/main/src/agent/types.ts"
click node_node_agent_utils "https://github.com/langchain-ai/openwiki/blob/main/src/agent/utils.ts"
click node_node_env "https://github.com/langchain-ai/openwiki/blob/main/src/env.ts"
click node_node_credentials "https://github.com/langchain-ai/openwiki/blob/main/src/credentials.tsx"
click node_node_constants "https://github.com/langchain-ai/openwiki/blob/main/src/constants.ts"
click node_node_wiki "https://github.com/langchain-ai/openwiki/tree/main/openwiki"
click node_node_update_state "https://github.com/langchain-ai/openwiki/blob/main/openwiki/.last-update.json"
click node_node_agents_md "https://github.com/langchain-ai/openwiki/blob/main/AGENTS.md"
click node_node_claude_md "https://github.com/langchain-ai/openwiki/blob/main/CLAUDE.md"
click node_node_github_update "https://github.com/langchain-ai/openwiki/blob/main/.github/workflows/openwiki-update.yml"
click node_node_examples "https://github.com/langchain-ai/openwiki/blob/main/examples/openwiki-update.yml"
click node_node_checks "https://github.com/langchain-ai/openwiki/blob/main/.github/workflows/checks.yml"
click node_node_package "https://github.com/langchain-ai/openwiki/blob/main/package.json"
click node_node_eslint "https://github.com/langchain-ai/openwiki/blob/main/eslint.config.js"
click node_node_tsconfig "https://github.com/langchain-ai/openwiki/blob/main/tsconfig.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_commands,node_node_agent,node_node_prompt,node_node_agent_types,node_node_agent_utils toneBlue
class node_node_env,node_node_credentials,node_node_constants toneAmber
class node_node_wiki,node_node_update_state,node_node_agents_md,node_node_claude_md toneMint
class node_node_github_update,node_node_examples toneRose
class node_node_checks,node_node_package,node_node_eslint,node_node_tsconfig toneIndigo
```

## Components

### Runtime

CLI entrypoint, orchestration, and agent execution.

- [CLI entry](https://github.com/langchain-ai/openwiki/blob/main/src/cli.tsx): ts entrypoint · Parses flags and starts the command flow. · `src/cli.tsx`
- [Commands](https://github.com/langchain-ai/openwiki/blob/main/src/commands.ts): orchestrator · Routes init, update, and interactive modes. · `src/commands.ts`
- [Agent loop](https://github.com/langchain-ai/openwiki/blob/main/src/agent/index.ts): doc agent · Drives the documentation-writing workflow. · `src/agent/index.ts`
- [Prompting](https://github.com/langchain-ai/openwiki/blob/main/src/agent/prompt.ts): prompt spec · Defines the instructions passed to the model. · `src/agent/prompt.ts`
- [Agent types](https://github.com/langchain-ai/openwiki/blob/main/src/agent/types.ts): data types · Agent-facing structures and contracts. · `src/agent/types.ts`
- [Agent utils](https://github.com/langchain-ai/openwiki/blob/main/src/agent/utils.ts): helpers · Supporting logic for the agent subsystem. · `src/agent/utils.ts`

### State & config

Local settings, credentials, and update tracking.

- [Environment](https://github.com/langchain-ai/openwiki/blob/main/src/env.ts): config loader · Loads provider and runtime settings. · `src/env.ts`
- [Credentials](https://github.com/langchain-ai/openwiki/blob/main/src/credentials.tsx): local setup · Manages API keys and local persistence. · `src/credentials.tsx`
- [Constants](https://github.com/langchain-ai/openwiki/blob/main/src/constants.ts): shared config · Central shared constants used across the CLI. · `src/constants.ts`

### Documentation workspace

Generated docs and repository-adjacent instructions.

- [OpenWiki docs](https://github.com/langchain-ai/openwiki/tree/main/openwiki): generated workspace · Primary documentation tree written and refreshed by the tool. · `openwiki`
- [Last update](https://github.com/langchain-ai/openwiki/blob/main/openwiki/.last-update.json): checkpoint · Tracks the previous successful generation run. · `openwiki/.last-update.json`
- [Agent guides](https://github.com/langchain-ai/openwiki/blob/main/AGENTS.md): repo instructions · Repository-facing guidance appended for future agents. · `AGENTS.md`
- [Claude guide](https://github.com/langchain-ai/openwiki/blob/main/CLAUDE.md): repo instructions · Repository-facing guidance appended for future agents. · `CLAUDE.md`

### Automation

Scheduled maintenance and CI entry points.

- [Update workflow](https://github.com/langchain-ai/openwiki/blob/main/.github/workflows/openwiki-update.yml): github action · Scheduled run that refreshes docs and can open a PR. · `.github/workflows/openwiki-update.yml`
- [Example workflow](https://github.com/langchain-ai/openwiki/blob/main/examples/openwiki-update.yml): example config · Sample setup for running OpenWiki updates. · `examples/openwiki-update.yml`

### Tooling

Validation and project scaffolding.

- [Checks workflow](https://github.com/langchain-ai/openwiki/blob/main/.github/workflows/checks.yml): ci workflow · Validation pipeline for the repository. · `.github/workflows/checks.yml`
- [Package scripts](https://github.com/langchain-ai/openwiki/blob/main/package.json): node project · Defines the CLI package and execution scripts. · `package.json`
- [ESLint config](https://github.com/langchain-ai/openwiki/blob/main/eslint.config.js): lint config · Static analysis rules for the codebase. · `eslint.config.js`
- [TS config](https://github.com/langchain-ai/openwiki/blob/main/tsconfig.json): build config · TypeScript compiler settings. · `tsconfig.json`

## Connections

- CLI entry → Commands: dispatches · CLI flags are routed into the command boundary.
- Commands → Environment: loads · Commands read provider/runtime configuration.
- Commands → Credentials: sets up · Commands handle API key and local setup.
- Commands → Agent loop: runs · Interactive and update flows invoke the agent loop.
- Commands → OpenWiki docs: writes · Documentation updates are materialized in the workspace.
- Commands → Last update: tracks · Incremental runs consult and refresh update checkpoints.
- Agent loop → Prompting: uses · The agent loop applies prompting instructions.
- Agent loop → Agent types: structures · Agent state and outputs are typed here.
- Agent loop → Agent utils: depends on · Supporting helper logic feeds the agent loop.
- Environment → Constants: shares · Configuration is anchored by shared constants.
- Credentials → OpenWiki docs: updates docs · Setup guidance is reflected in the documentation workspace.
- OpenWiki docs → Agent guides: references · The workspace connects to repository agent instructions.
- OpenWiki docs → Claude guide: references · The workspace connects to repository agent instructions.
- Update workflow → CLI entry: invokes · The scheduled workflow reruns the CLI.
- Example workflow → Update workflow: mirrors · Example automation reflects the update workflow.
- Checks workflow → Package scripts: validates · CI runs the project scripts and checks.
- Checks workflow → ESLint config: uses · CI enforces lint rules.
- Checks workflow → TS config: uses · CI validates TypeScript compilation settings.
