Quick Start

This tutorial walks you through a complete end-to-end workflow in architxt: importing entities, uploading design documents, syncing to Hindsight, building a contextual graph, and composing a curated page. The sample files are already in the repo under docs/.

Video walkthrough

Prefer to watch? There is a full video walkthrough of this tutorial on YouTube: architxt Quick Start.

Before you start

Make sure you have completed Prerequisites and Installation. You need:

• architxt backend and UI running.
• Docling available and a GPU recommended for larger PDFs.
• An LLM provider configured in server/.env.
• A Hindsight server running.

1. Prepare the knowledge base

Create a context

1. In the architxt UI, open Contexts from the left nav.

2. Click the Add button (plus icon) in the toolbar.

3. Create a new context and set the description to:

   Component Designs: a document outlining design changes for a software component.

Contexts do not have a separate name field; the description is the only label. This context groups the documents and entities you are about to import.

Create tags (optional)

1. Open Tags from the left nav.
2. Click Add and create tags such as design, gateway, or component.
3. You can apply tags to documents later when uploading or from the Documents toolbar.

Create entity types

1. Open Entities from the left nav.
2. In the Template Roles section, click Add to create the entity types used by the import file (for example Component, Capability, External, Actor).
3. Match the labels to the entity_type column in the CSV below.

tip

For the tutorial, it is enough to create simple labels that match the CSV. The full entity model — including pattern matching, aliases, and boundary rules — is covered in the Entities section.

Import entities

1. Download the sample entity list: docs/entities/component-designs-entities.csv
2. In the architxt UI, go to Entities and click the Import button (download icon).
3. Select Import Entities, choose the CSV file, and import it.

You should see a batch of entities appear in the list.

2. Upload and process documents

Upload two design documents

Download the two sample design docs:

• docs/designs/component-doc-processing.md
• docs/designs/component-eig-gateway.md

1. In the UI, open Documents from the left nav.
2. Click the Add button (plus icon) and upload both files.
3. Assign the Component Designs context and any optional tags using the toolbar buttons:
   • Context — assign the context to the selected documents.
   • Tags — apply tags to the selected documents.

Extract the documents

1. Select both uploaded documents in the Documents table.
2. Click the Extract button in the toolbar.
3. Wait until both documents show status Extracted.

tip

Watch the extraction progress in the daemon status monitor in the header bar (spinner icon). Click it to see which documents are currently extracting.

Insert entities and set the document date

For each extracted document:

1. Click the document row to open the View Document dialog.
2. Use the entity detection panel to review proposed entity tags and insert them into the document text.
3. Close the dialog and return to the Documents list.
4. Select both documents, click Config in the toolbar, and set the Document Date.

3. Connect Hindsight

If you started architxt with the hindsight Docker Compose profile, this step is already done: the profile registers a default Hindsight server at http://hindsight:8888 and creates a memory bank named architxt. You can skip straight to 4. Sync architxt data into Hindsight and pick the pre-configured server and bank from the dropdowns.

For local development or a manually started Hindsight server, follow the steps below.

Add a Hindsight server

1. Open Servers from the left nav.

2. Click Add Server.

3. Enter the Hindsight API endpoint. For a local Hindsight server:

   http://localhost:8888

4. Click Save Changes.

The new server should appear in the Servers table.

Set the Hindsight API key (if needed)

If your Hindsight server requires an API key:

1. Open Servers and click the server row to open View Server.
2. Add the API key in the server settings and click Save Changes.

For local Hindsight servers this is often not required.

Create a bank in Hindsight

Banks live in Hindsight, not in architxt. Create the bank using either the Hindsight Control Plane UI or the Hindsight CLI. You will select that bank inside architxt in the next section.

4. Sync architxt data into Hindsight

Open Hindsight Sync from the left nav.

Sync bank settings

1. Select your Hindsight server and bank from the dropdowns.
2. Change the object selector to Bank Settings.
3. Click Fetch Bank Settings.
4. Select the bank-settings row and click Push to Bank.

Sync entities

1. Change the object selector to Entities.
2. Click Fetch Entities.
3. Select all entity rows that are Only on architxt and click Push to Bank.
4. Wait for the push to complete.

Sync documents

1. Change the object selector to Documents.
2. Click Fetch Documents.
3. Select both design documents and click Push to Bank.
4. Wait for the Hindsight retain operations to finish. You can check pending operations from the Hindsight Sync page.

tip

Click the daemon status monitor in the header bar to open the operations polling dialog and watch Hindsight retain/push progress, similar to the document extraction monitor.

5. Enable automatic graph sync

1. Return to Servers and click Banks on the Hindsight server row.
2. Select the checkbox for the bank you are using.
3. Set the mode to Auto. This lets the sync daemon reach full sync without manual runs.
4. Uncheck Discovery. Discovery is experimental and its output is not directly consumable yet.
5. Click Save.

6. Run the contextual-graph sync job

1. Open Context Patches → Sync Jobs from the left nav.
2. Click the Run sync job button and confirm.

The first run imports the grounded entity graph from Hindsight and builds the initial context patches (mental models). You should see something like this in the Import Skeleton stage:

{
  "success": true,
  "imported": {
    "nodes": 20,
    "edges": 31
  },
  "skipped": {
    "nodes": 0
  },
  "stale": {
    "nodes": 0,
    "edges": 0
  },
  "restored": {
    "nodes": 0,
    "edges": 0
  }
}

Then the Deploy Model stage composes and pushes mental models. Some edges may be skipped because of the bank restriction value. They are retried on the next sync run:

{
  "success": true,
  "queued": {
    "entitySummary": 20,
    "entityCapabilities": 20,
    "edge": 31,
    "discover": 0,
    "total": 71
  },
  "composed": ["entity-summary-A-C:EIG-001", "..."],
  "pushed": ["entity-summary-A-C:EIG-001", "..."],
  "unchanged": [],
  "failed": [],
  "skipped_by_restriction": 21
}

tip

Wait for all Hindsight operations to finish before diagnosing mental-model issues. The sync daemon will retry restricted items on the next run.

Inspect the graph

On the same Context Patches page, open the Graph tab. You will see:

• Entities from Hindsight.
• Grounded edges with a red side marker.
• Contextual edges derived from the EDGE CONTEXT patch for each grounded edge.

Each grounded edge can have zero or more contextual edges attached.

Refresh mental models after consolidation

1. Open Mental Models from the left nav.
2. For each model, set Refresh after consolidation to ON.
3. Click Save Changes for each model.

This keeps mental models up to date on subsequent sync runs.

7. Compose a curated page

1. Open Workspace from the left nav.
2. If no workspace session exists, a default session called Workspace session is created automatically.
3. In the Pages panel, click the Add page button (plus icon) to create a new curated page.
4. Select an item from the Contextual Data list to preview it.
5. Hover over a section heading in the preview to reveal:
   • Evidence — see supporting facts.
   • Focus — narrow the section.
   • Add to page — copy the section into a curated page.
6. Click Add to page and choose the curated page you created.
7. Repeat until the curated page contains the sections you want.
8. Click Save active page to persist the page.

The page name shows in italics while there are unsaved edits, and the Save button becomes enabled.

What you have built

You now have:

• A populated entity set and two extracted design documents.
• A Hindsight bank retaining entities and documents.
• A contextual graph grounded on Hindsight, with mental models deployed.
• A curated workspace page composed from contextual data.

From here you can add more documents, run further sync jobs, adjust mental-model settings, or build additional curated pages.