Get Started with ContextDx

Welcome to ContextDx. You're about to turn scattered architecture knowledge into a living, queryable system map. We'll get you from zero to a working board in under 15 minutes.

ContextDx builds a living knowledge graph from your code, infrastructure, documentation, and observability systems. You query it in natural language; it returns architectural intelligence scoped to your board context.

Core workflow: Sources → Boards → Insights → Agent → Publish

Rendering diagram...

Prerequisites

ContextDx instance running (cloud or self-hosted)
Portal account with an invitation email from your org admin
At least one of: a code repo, architecture docs, or a URL to paste

Access Your Workspace

Click your invitation link and sign in with SSO
Select your primary role (Developer, Architect, CTO, Product Manager, etc.)
You'll land in your workspace with a Master Board already waiting

Your role selection customizes how the AI responds — a developer asking "What are the system boundaries?" gets a different answer than a CTO asking the same question.

1. Create Sources

Sources are the raw inputs ContextDx uses to build your architecture graph. They live in a workspace-level Sources Catalog — set them up once, bind them to any board.

Deep dive: Sources concept | Connecting Sources guide

Pick your starting point

ADRs, architecture briefs, Confluence spaces, design docs — this is the fastest path.

Add your docs as sources — Confluence, Web URL, or Inline Text
Bind them as governing sources to a board
ContextDx's AI agents extract services, dependencies, boundaries, and constraints
Review extracted nodes/edges before committing to the board

Tip

Web URL and Inline Text need zero setup — just paste a URL or markdown. Start there if you want instant results.

Source types at a glance

Category	Sources	Auth
Code	GitHub Repo, GitHub File	OAuth
Documentation	Confluence, Google Docs, Notion	OAuth
Infrastructure	Terraform, CloudFormation	API key
Project	Jira	OAuth
Communication	Slack	OAuth
Observability	Sentry, LogRocket	OAuth
Quick-add	Web URL, Inline Text	None
Plugin	Board Builder	API headers

Deep dive: Integrations Reference

Binding roles

When you bind a source to a board, you assign a role:

Governing — participates in sync, creates/modifies nodes and edges. This is your source of truth.
Reference — context only. Available for AI queries but never mutates the board graph.

2. Build Boards

Boards are graph representations of your architecture — nodes (components) and edges (relationships) that stay synchronized with your sources.

Deep dive: Workboards concept | Workboards Guide

Your Master Board

Every workspace gets a Master Board automatically — the top-level overview of your entire system landscape. Think of it as an L0 view: 10–30 nodes representing major domains, services, and external integrations.

Example: An e-commerce platform

Rendering diagram...

Each internal node can drill down into its own detail board. External nodes (Stripe) and infrastructure (PostgreSQL) stay as leaf nodes — you don't own their internals.

Archetypes

Every node has an archetype — a classification that determines its visual representation and relationship rules:

Archetype	Represents	Examples
Service	Business logic, domain handlers	OrderService, AuthService
API	HTTP endpoints, gateways	REST controllers, API Gateway
Database	Persistence, data stores	PostgreSQL, Redis, DynamoDB
Component	UI elements, frontend modules	React components, Vue pages
Queue	Message brokers, event buses	SQS, Kafka, RabbitMQ
External	Third-party integrations	Stripe, Twilio, Auth0

Why archetypes matter

Consistent visual language — every team reads the board the same way
Typed relationships — archetypes constrain which edge types make sense (a Service writes-to a Database, not the reverse)
Query intelligence — when you ask "what depends on our payment system?", the archetype tells the AI what kind of component it's reasoning about

Workspaces can define custom archetypes beyond defaults. If your domain has first-class concepts (e.g., "Plugin", "Adapter", "Saga"), create custom archetypes with their own icons, colors, and relationship rules.

Deep dive: Organization Settings

Drill-down layers

Boards support a layered hierarchy — click into any node to see its internals:

Layer	Scope	Typical nodes	What you see
L0 — Overview	Entire system	10–30	Domains, services, external integrations
L1 — Domain	Single service	10–40	Controllers, services, repositories, models
L2 — Component	Single module	5–20	Classes, handlers, internal wiring

Building layers with Board Builder

Each codebase (or subdirectory in a monorepo) gets its own analysis:

BASH
/analyze                              # L0: system overview
/analyze --drill overview/api-gateway # L1: API gateway internals
/analyze --all                        # All layers progressively
/sync --all                           # Push entire hierarchy

Layer boards link to parents via layerBoardSlug references — navigation is automatic.

Board types

Type	Purpose
Master Board	Top-level system overview
Context Map	Domain boundaries, team ownership (DDD)
System	Services, databases, APIs, queues
Diagram	Data flows, sequence diagrams, topology
Domain Model	Entity relationships, aggregate boundaries
Generated	Auto-generated from code or infra analysis

Deep dive: Nodes & Edges | Permissions & Access

3. Build Insights

Insights are analytical overlays generated from your board's architecture graph and bound sources. They surface patterns, risks, and opportunities you might not spot by staring at a node graph.

Deep dive: Insights concept | Insight Skills guide

From any board, request an insights analysis. ContextDx examines the board's nodes, edges, and bound source content, then produces structured findings:

Services handling PII without encryption at rest
Public-facing APIs calling internal services without auth boundaries
Third-party integrations with overly broad permissions
Missing rate limiting on ingestion endpoints

Tip

Insights get dramatically better when your board has governing sources bound. The AI can cross-reference code structure with documentation to find things neither reveals alone.

4. Query with the Agent

The conversational agent is your interface to architectural intelligence. It has full context of the board's graph, bound sources, and generated insights.

Deep dive: Chat concept | Chat guide

Open the conversation panel on any board and query in natural language:

"What are the system boundaries for checkout?"
"How would adding subscriptions impact the payment domain?"
"Which services share database tables? What are the coupling risks?"
"Explain the auth flow for a new engineer joining the team."

Response formats

Format	Use case
Conversational	Quick answers, exploratory questions
Structured Board	Generate a new board from the response
With Insights	Visual patterns overlaid on architecture
Insights + Research	Deep analysis with citations from sources
Adopt as Governing	Apply source content to board structure

Agent personalities

Personality	When to use
Pragmatist	Direct answers, minimal preamble
Advisor	Trade-off analysis, decision support
Analyst	Objective comparison of conflicting sources
Explorer	Discover hidden dependencies and patterns
Documenter	Generate structured documentation
Technical Translator	Bridge technical ↔ business language
Compliance Guardian	Security, regulatory, and risk focus

Tips for better queries

Be specific — "What depends on the auth service?" beats "Tell me about auth"
Provide context — "We're planning to migrate to microservices" frames the answer
Use follow-ups — The agent remembers conversation context across turns
Match format to purpose — Use "Structured Board" for documentation, "Conversational" for exploration

5. Publish Boards

Once your boards are built and enriched with insights, publish them for organizational consumption.

Deep dive: Publishing Boards | Permissions & Access

Publishing creates a shareable, read-only snapshot with interactive navigation, insights overlays, and documentation sections. Control access at the board level:

Visibility	Who can view
Public	Anyone with the URL
Unlisted	Only people with the direct link
Protected	Requires a password or share token

Published boards update when you re-publish — the URL stays stable, the content reflects your latest sync.

Startup Checklist

Signed in and selected your role
Created at least one source (Web URL or Inline Text is fastest)
Bound source to your Master Board as governing
Triggered a sync and reviewed extracted nodes
Ran an insight analysis (try Security or Dependency)
Asked the agent a question about your architecture
Published the board for a teammate to see

Tip

You don't need all 5 steps in one sitting. Most teams start with Sources + Boards and add Insights and Publishing as they go. The architecture builds incrementally.

Common Questions

How current is the data?

Sources sync continuously. Most changes appear within 5–15 minutes. Board Builder sources update when you re-run /analyze and /sync.

Can I query systems I don't have code access to?

Yes. ContextDx provides architectural context based on your role permissions, not code repo access. If the architecture is mapped on a board you can see, you can query it.

What if I get an answer I don't understand?

Ask follow-up questions. Try: "Explain that in simpler terms" or "What does that mean for [my specific concern]?" The agent adapts to your level.

How do I report incorrect information?

Click the feedback icon on any response. Your architects will review and update the architecture graph.

What's Next

Core Concepts

Understand workspaces, boards, nodes, sources, and insights in depth.

Claude Code Plugin

Analyze your codebase and push architecture to ContextDx from Claude Code.

For Architects

Map systems, enforce governance, and maintain architectural clarity.

For Developers

Explore inherited systems, trace dependencies, and assess impact.