Skip to content
CTN Documentation
Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

Query the arc42 Documentation with AI Tools

This guide explains how anyone in the team can ask questions about the CTN arc42 architecture documentation using their own AI assistant — including Claude, ChatGPT, Google Gemini, GitHub Copilot, Perplexity, Cursor and JetBrains Junie — by connecting it to the GitHub repository where the documentation lives.

The tools fall into three groups: assistants that connect to GitHub directly (Claude, ChatGPT, Copilot, Gemini), AI code editors that read the project after you open it (Cursor, JetBrains Junie), and tools that work from a public URL (Perplexity). Pick whichever you already use.

Overview

Section titled “Overview”

The arc42 documentation is the single source of truth for the CTN architecture. The source markdown files live in the public GitHub repository:

Because the repository is public, every team member can point their AI tool at it and ask questions such as “How does association onboarding work?” or “Which ADR describes the token claim composition?” — and get answers grounded in the actual documentation, with references back to the source files.

The AI provider interfaces below change regularly and most of these connectors are still in beta. If a menu item looks slightly different, search the tool’s help for “GitHub” — the overall flow is the same: connect GitHub, select this repository, then ask your question.

Prerequisites

Section titled “Prerequisites”
  • An account for the AI tool you want to use (Claude, ChatGPT or Gemini).
  • Access to the repository. It is public, so no special permissions are needed for reading. If it is ever made private, you will need to authorize the connector with a GitHub account that has access (and possibly GitHub-organization admin approval).

Option 1 — Claude (claude.ai)

Section titled “Option 1 — Claude (claude.ai)”

Claude has a built-in GitHub integration that lets you attach repository files directly to a conversation.

  1. Open a new chat at claude.ai.
  2. Click the + button in the lower-left corner of the message box.
  3. Choose Add from GitHub.
  4. If this is your first time, you will be redirected to GitHub to authenticate / authorize Claude. Approve access.
  5. In the file browser, navigate to Basic-Data-Infrastructure/CNCL-BDI and select the docs/arc42 folder (or specific files you care about).
  6. Send your question. Claude reads the selected content and answers based on it.

Tips

  • You can add multiple folders or repositories as long as they fit in Claude’s context window. For broad questions, selecting the whole docs/arc42 folder works well.
  • When the documentation is updated, click Sync now to pull the latest changes into your chat.

Option 2 — ChatGPT (chatgpt.com)

Section titled “Option 2 — ChatGPT (chatgpt.com)”

ChatGPT connects to GitHub as an “app” / connector, after which it can read code, README and documentation files from the repositories you grant access to.

  1. In ChatGPT, open Settings → Apps (also called Connectors).
  2. Find GitHub in the app directory and click to connect.
  3. You are sent to GitHub to install and authorize the ChatGPT app. Grant it access to the CNCL-BDI repository (or all repositories you are allowed to share).
  4. Wait a few minutes — there is typically a ~5-minute delay before a repository shows up as available in ChatGPT.
  5. Start a chat, enable the GitHub connector (or use Deep research → GitHub for thorough, cited answers), and ask your question about the arc42 docs.

Tips

  • If the repository does not appear, open Settings → Apps → GitHub → Choose repositories and make sure CNCL-BDI is selected.
  • For a brand-new or private repository that will not show up, you can nudge GitHub’s index by running a search on GitHub itself in the form repo:Basic-Data-Infrastructure/CNCL-BDI.

Option 3 — Google Gemini (gemini.google.com)

Section titled “Option 3 — Google Gemini (gemini.google.com)”

Google’s general-purpose AI assistant is Gemini. The Gemini web app can import a GitHub repository directly into a prompt.

  1. Open gemini.google.com.
  2. In the prompt box, click Add file (the attach/+ control).
  3. Choose Import code.
  4. Paste the repository or branch URL: https://github.com/Basic-Data-Infrastructure/CNCL-BDI (you can also point at the docs/arc42 path or a specific branch).
  5. Click Import, then ask your question about the architecture.
Section titled “Recommended alternative: NotebookLM”

For document-style question-and-answer work, Google’s NotebookLM is often a better fit than the Gemini chat app. It gives source-grounded, citation-backed answers from exactly the documents you add.

  1. Open NotebookLM and create a new notebook.
  2. Add the arc42 documents as sources — the simplest approach is to paste the GitHub file/folder URLs, or download the documents and upload the markdown files.
  3. Ask questions; NotebookLM answers only from the sources you provided and cites them.

Option 4 — GitHub Copilot

Section titled “Option 4 — GitHub Copilot”

If you already use GitHub Copilot, you can ask questions about the repository without any extra setup — Copilot Chat works directly on GitHub when you are in the context of the repository.

  1. Open the repository on GitHub: Basic-Data-Infrastructure/CNCL-BDI.
  2. Click the Copilot icon in the top navigation bar. A chat panel opens on the page you are viewing.
  3. Ask your question. Because you are in the repository’s context, Copilot automatically indexes it and answers based on its contents — e.g. “Summarise the arc42 deployment chapter in docs/arc42.”
  4. As you browse to specific files, pull requests or issues, they are attached as context, so you can narrow your questions to, for example, docs/arc42/09-decisions.

Tips

  • The same Copilot Chat is available in your IDE (VS Code, Visual Studio, JetBrains) and in GitHub Mobile — handy if you prefer to work where the code is.
  • A GitHub Copilot license is required (individual or provided through your organization).

Option 5 — Perplexity

Section titled “Option 5 — Perplexity”

Perplexity has no GitHub connector, but it reads public web pages — which is all you need, because the repository is public.

  1. Open perplexity.ai.
  2. Paste a public URL into the prompt and ask your question. Two good choices:
    • A specific file or folder in the repo, e.g. a chapter under docs/arc42.
    • The published llms-full.txt (the entire documentation in one file — see Alternative below), which gives Perplexity the full context in a single link.
  3. Perplexity answers with citations back to the source.

Tip: For repeated use, create a Space in Perplexity and add the URLs as sources, so every question in that Space is grounded in the arc42 documentation.

Option 6 — Cursor

Section titled “Option 6 — Cursor”

Cursor is an AI code editor. It is a good fit for team members who already work in an IDE, because it answers from the project you have open.

  1. Clone the repository (or open a copy you already have):

    Terminal window
    git clone https://github.com/Basic-Data-Infrastructure/CNCL-BDI

  2. Open the folder in Cursor.

  3. Open the chat (Cmd/Ctrl + L), reference the docs with @ — for example @docs/arc42 or @Codebase — and ask your question. Cursor indexes the project and answers from it.

Option 7 — JetBrains Junie

Section titled “Option 7 — JetBrains Junie”

Junie is JetBrains’ AI coding agent (it creates the .junie folder in a project). This is the setup used at Conclusion.

  1. Open the CNCL-BDI project in a JetBrains IDE (IntelliJ IDEA, PyCharm, etc.) with the Junie plugin — or run the Junie CLI from inside the project folder.
  2. In the Junie chat, reference files or folders with @ (e.g. @docs/arc42) and ask your question. Junie reads the referenced documents and answers from them.
  3. Project context for Junie lives in .junie/guidelines.md (or AGENTS.md) in the repository root. Because it is committed to the repo, the whole team shares the same context and gets consistent answers. The arc42 documents themselves are in docs/arc42.

What you can ask

Section titled “What you can ask”

Once connected, useful questions include:

  • “Summarise chapter 5 (Building Blocks) of the CTN arc42 documentation.”
  • “Which architecture decision (ADR) covers external IdP federation, and what was decided?”
  • “Explain the difference between users and members in the CTN context.”
  • “What are the main risks listed in the arc42 documentation?”
  • “Define the glossary terms used in the association onboarding flow.”

Keeping answers up to date

Section titled “Keeping answers up to date”

These tools read a snapshot of the repository at the time you connect or sync. After the documentation is updated on GitHub, use the tool’s refresh/sync option (or re-import) so the AI sees the latest version.

Alternative: the published documentation site

Section titled “Alternative: the published documentation site”

If you would rather not connect GitHub at all, the CTN documentation portal automatically publishes machine-readable versions of the docs for AI tools:

Paste either URL into any AI tool that accepts a link (Perplexity, Claude, ChatGPT, Gemini, …) and ask your questions from there. The llms-full.txt file contains the complete documentation, so it gives the AI the most context in a single link.

References

Section titled “References”

In samenwerking met

Connected Trade NetworkConclusionData in LogisticsContargoInland Terminals GroupVan Berkel