Last updated April 21, 2026
Connecting Sources
Architecture that drifts from reality is worse than no architecture at all. Sources are how you anchor your boards to actual code, docs, and infrastructure — so your views stay current as systems change.
Prerequisites
Before connecting sources, make sure you have:
- A workspace set up with at least one board
- Admin or editor permissions on the workspace
- OAuth connectors configured (for provider sources like GitHub, Confluence)
- Or just a URL or text to paste (no setup needed for Web URL and Inline Text)
How sources work
Sources live in a workspace-level catalog. You register a source once, then bind it to one or more boards. Each binding defines the source's role and tracks its own sync state independently.
Rendering diagram...
Adding your first source
The fastest way to get started depends on what you have:
No OAuth needed — just paste a URL.
- Open your workspace → Sources
- Click Add Source → select Web URL
- Paste the URL (blog post, vendor docs, internal wiki, ADR page)
- Give it a title and save
Works with any HTTP/HTTPS page — architecture blog posts, AWS docs, Stripe API docs, tech specs on static sites.
Source types
| Type | Auth | Best for |
|---|---|---|
| GitHub Repo | OAuth | Full repo analysis |
| GitHub File | OAuth | Specific file tracking |
| Confluence | OAuth | Wiki pages, ADRs |
| Google Docs | OAuth | Design docs, specs |
| Notion | OAuth | Knowledge bases |
| Jira | OAuth | Issue context |
| Terraform | API key | Infrastructure state |
| CloudFormation | API key | AWS stacks |
| Web URL | None | Any webpage |
| Inline Text | None | Direct markdown input |
| Board Builder | API headers | External plugin push |
Binding sources to boards
Once a source is in your catalog, bind it to a board:
- Open a board → click the Sources panel
- Click Bind Source → select from the catalog
- Choose a role:
| Role | What it does |
|---|---|
| Governing | Participates in sync — contributes nodes and edges to the board |
| Reference | Attached as context only — the AI can read it, but it won't modify the graph |
A board can have governing sources of only one classification type. Choose wisely — governing sources drive the actual structure of your board.
The sync workflow
When you sync a governing source, the platform walks through five states:
Rendering diagram...
Each binding tracks its own state and timestamp — so you always know what's current.
Sync resumption
If sync fails at any stage, the binding stays at the last successful state. Re-triggering sync resumes from where it left off — the platform doesn't restart collected evidence or regenerate embeddings you've already paid for.
Health monitoring
Sources are continuously checked for accessibility:
| Status | Meaning |
|---|---|
| Healthy | Source accessible, sync working |
| Degraded | Source accessible but with issues |
| Failing | Source not accessible or sync failing |
Keep an eye on degraded sources. They often signal an expiring OAuth token or a renamed repo — fix them before they go failing.
A failing source doesn't break your board — it just means the data may be stale.
Board Builder sources
Board Builder is how external plugins (Claude Code, VS Code, JetBrains) push structured architecture data directly to your boards. Instead of ContextDX pulling and interpreting source content, the plugin does the analysis and pushes a ready-made graph.
When to use Board Builder
Board Builder sources authenticate via API headers (token + secret) rather than OAuth. Use this when:
- You want code-derived architecture — static analysis that reads the actual codebase structure
- You have infrastructure-as-code to visualize (AWS CDK, Terraform) and want faithful component mapping
- You need incremental updates tied to git diffs, not full content re-extraction
See the Board Builder API reference for payload shape and auth.
Troubleshooting
Source shows "failing" health status
Cause: The external service is unreachable or the OAuth token has expired.
Fix:
- Go to Settings → Integrations and check if the connector is still connected
- If expired, click Reconnect to re-authorize
- Return to Sources and check if health updates to healthy
Sync stuck at "evidence collected"
Cause: Embedding generation may have hit a rate limit or the AI service is temporarily unavailable.
Fix:
- Wait a few minutes and re-trigger sync
- Check that your organization's LLM API credentials are valid in the platform's App Environment settings
Start with Web URL or Inline Text — zero setup, instant results. Graduate to OAuth sources once you've seen the value.