This is the documentation of version 0.8.2. The newest version is 0.9.2: go to the newest documentation

User guide

1. What Loonar Compass is

Loonar Compass is a standalone Windows desktop application: an AI assistant for working with an Enterprise Architect model (Sparx Systems). You write to it in plain language, and it:

• reads the model (packages, elements, diagrams, connectors, attributes and operations) and describes what is in it,
• analyzes the model: the impact of changing an element on the rest of the model, where operations are used, elements without connectors,
• changes the model: creates packages, diagrams, elements and connectors, adds attributes and operations to classes, sets keywords and tagged values, lays out elements on diagrams, moves them, removes an element from a diagram, deletes objects from the model, colors them, adds legends, copies packages and creates baselines of them,
• keeps the EA project glossary (terms with their meaning and type) and structured scenarios of elements (actor and system steps),
• draws diagrams from a description, a photo, a sketch or an attached file,
• shows diagrams as images in the chat, just as Enterprise Architect draws them,
• prepares documents from the model's content: Word, Excel, PNG images and Confluence pages, also based on templates,
• remembers notes between conversations (modeling conventions, preferences, corrections).

The application uses an AI language model over the Internet, with your API key: Claude Haiku 5.5 (Anthropic) by default; in the settings you can choose another Claude model or an OpenAI model (chapter 5). It connects to the EA model in two ways: it reads it directly (from the PostgreSQL database or from the .qea/.qeax file) and writes to it through Enterprise Architect, using the model user account given in the settings when the model has one. With a model file you have open in EA, the changes go through your EA window; otherwise EA runs in the background.

The interface and the assistant's answers are available in four languages: Polish, English, German and French (chapter 5). Answers and changes are prepared by an AI model and may contain errors: review them before you approve them (chapter 16).

Loonar Compass runs as a separate window, started from the Start menu, or as a window docked in Enterprise Architect itself, which works with the project open in that EA window (chapter 10).

Without a window, Compass also checks the model in CI pipelines (chapter 23), and the separate program Compass Hub serves the team's models to people and tools (chapter 22).

4. Application window and navigation

On the left side of the window there is a navy-blue navigation bar with icons. When you hover the mouse over an icon, its name appears. Clicking switches the view.

An orange “!” on the Settings, Assistant memory and Document templates icons means that after a language change the translation has not finished yet (chapter 5).

Support the project. Loonar Compass is free, also for commercial use, and it will stay free. If it saves you time, you can support its development with a voluntary contribution: the Support on suppi.pl button opens suppi.pl/loonar. The contributions pay, among other things, for a code-signing certificate. Other ways to help: report bugs and ideas (Report a bug), recommend the application to other Enterprise Architect users or star the project on GitHub.

Chat view

• The list of conversations on the left is grouped into “Today”, “Yesterday”, “Last 7 days” and “Earlier”. You start a new conversation with the + button. The selected conversation is highlighted.
• The conversation header shows its title, the Model: … button with the model of the conversation (chapter 17) and, while the assistant is working, the “The assistant is working” indicator.
• Messages: yours are in a beige bubble, the assistant's answers have the application icon. Each message shows the time (older ones also the date).
• The new conversation screen shows the logo, a hint about what you can do, and which EA model the conversation will use, with the Choose another model… and Confirm the model and start buttons (chapter 17).
• The message card at the bottom: the text field, the paste button, the model and approval mode, and the round send and stop buttons (chapter 6). Below the card, a reminder says that answers and changes are prepared by an AI model.

5. Settings and language

The Settings view has eleven cards: AI model and Language and change approval in the left column, Model and Enterprise Architect in the right one, and below them New releases (newsletter), Confluence and Miro. In Compass opened in Enterprise Architect, there are no Model and Enterprise Architect cards, because the model is the project open in that EA window (chapter 10). You save each card separately with the button below the card, and the application immediately checks that the details work. The result appears below the button: green with a description or red with the cause of the error.

An empty password or key field means “no change”. The label saved next to a field indicates that the value is already stored. The API keys, the passwords and the Confluence and Miro tokens are kept in Windows Credential Manager, never in the settings file. The database password must not contain a semicolon (;), because Enterprise Architect cannot pass it in its connection string.

Default values. When there are no settings yet, the server, database name, EA user account and password fields are empty (the Server field shows the gray hint “e.g. 127.0.0.1”), the port is 5432, the database user is postgres, the path to EA.exe is C:\Program Files\Sparx Systems\EA\EA.exe, the approval mode is ask, the provider is Anthropic (Claude), the model is claude-haiku-5-5, the effort is “model default” and Max tokens is 10000. Existing settings are not changed.

Max tokens. If the assistant stops working with a message about a truncated answer, increase this value (for example to 20000). The limit costs nothing by itself: you pay for the text actually generated.

Locking of packages and elements while saving depends on the option “The model requires a lock to edit (Require User Lock to Edit)” on the Model card: select it when the model has “Require User Lock to Edit” turned on in EA.

AI model: provider, model and effort

The AI model card decides which language model answers in the conversations:

Save and test key checks the key with a short request to the chosen model. The data needed for the answers goes only to the chosen provider: to api.anthropic.com or to api.openai.com (chapter 18). If you change nothing on this card, the application works exactly as before: with Claude Haiku 5.5 and the model default effort. Larger models and higher effort cost more; Anthropic and OpenAI publish their prices.

Changing the language

The application works in four languages: Polish, English, German and French. You choose the language in the installer (English by default) and change it on the “Language and change approval” card:

1. Choose a language from the Language list.
2. Click Save. The interface switches to the new language, and the assistant answers in it from the next message.
3. The application carries your content over to the new language: it replaces untouched default templates with the versions in the new language, and the assistant's memory and your own and modified templates are translated by the AI model.

Only the memory and the templates are translated. Conversation history is never translated: conversations stay in the language in which you held them.

When you save the language, Compass also switches EA's own spell checker to that language, if EA has a dictionary for it. EA comes with English dictionaries only, so for other languages Compass checks the texts itself (chapter 7, “Spelling in the language of Compass”).

Database connection encryption

The Connection encryption field on the “Model” card (PostgreSQL database) decides whether the assistant reads the model over TLS:

• The connection test says whether the connection is encrypted: “The connection is encrypted (TLS).” or “The connection is NOT encrypted: the server does not offer TLS.”.
• With certificate verification, the name in the Server field must match the name in the server certificate.
• The database administrator can enforce TLS for all clients with hostssl entries in the pg_hba.conf file.
• The setting applies to the assistant's reading of the model. Enterprise Architect's own connection to the database (when saving) follows EA's settings.

6. Talking to the assistant

Writing

You type a message in the message card at the bottom of the window. The card contains the text field, the paste button, the model name and the current approval mode, and round buttons: Send and, while the assistant is working, Stop. Below the card you see the reminder: “Answers and changes are prepared by an AI model and may contain errors. Review them before you approve.”

The message field grows with the text. Spelling errors are underlined in red using the Windows system dictionary, in the language from the system settings. Right-click an underlined word and choose Add “…” to the dictionary: the word goes into the Windows dictionary, and a Polish expression goes in with all its forms (singular and plural, from the nominative to the vocative). In the same menu, Add “…” to the EA project glossary asks the assistant to add the term to the project glossary (chapter 7).

Attachments

You can attach up to 5 files to a message, each up to 10 MB. Ways to do it: drag files into the window (from Explorer or from a browser), paste them from the clipboard (Ctrl + V) or use the paste button in the message card.

While the assistant is working

• Below the messages you see the steps card: what the assistant is doing right now, how long it takes and a short result of each step (in Polish, German and French the short results are translated, and the technical details stay in English). While the assistant is working, the card is expanded, and when it finishes, it collapses to a single line; clicking the card header expands it again.
• You can keep writing: the next message goes into a queue and the assistant takes it into account at the next step, without interrupting its work.
• The Stop button stops the work after the current step. A step that is already running (for example saving to EA) is completed.
• An answer can take at most 24 steps. If the assistant has not finished by then, it stops so as not to run in an endless loop; send a new message (for example “continue”) to carry on.

What can the assistant do? The assistant knows the application's features from the changelog. Ask it: “What can you do in this application?”.

7. Working with the Enterprise Architect model

Write as you would to a colleague who knows EA. Refer to packages and diagrams by name. The assistant refers to model objects by name, package and GUID. Below are examples of requests; examples organised by goal are in chapter 8.

Reading

The diagram shown appears in the chat as an image. Below it are the Save as… and Open full size buttons.

Change impact analysis

The assistant goes from the given element along relationships deep into the model (up to 6 levels, in one or both directions, optionally only along selected relationship types). For each affected element it gives the relationship through which the impact arrives, the path from the starting element and the diagrams on which the element appears. You can get the result as a description, an image, a Word document or an Excel workbook.

Where operations are used

For a class, component or interface, the assistant finds where its operations (services) are called: on sequence diagrams (messages to the element or its lifeline) and activity diagrams (actions calling the operation), with the package and the caller. It also lists the operations not used on any diagram.

Drawing

BPMN subprocesses

• Embedded: the steps of the subprocess are its child elements and are drawn inside its rectangle on the same diagram.
• Collapsed: the steps are on a separate diagram, and double-clicking the subprocess opens that diagram. The assistant can also link a subprocess (or another element) to an existing diagram as a composite diagram.
• The assistant adds new steps to an existing subprocess.

Changes to an existing model

The assistant also changes the position and size of an element on a diagram without removing it (connectors stay), removes an element from a diagram while keeping it in the model, and changes the name, description and stereotype of an existing diagram.

Keywords and legends

The assistant sets elements' keywords (the Keywords field in EA) and tagged values, and creates a diagram legend with automatic coloring, as in EA: elements (by keyword, stereotype, status or type) and connectors (for example by stereotype) get a color from the legend, and the legend shows the value, color and label.

Connector lines

• Line style (like Line Style in EA): direct, auto routing, custom line, orthogonal square, orthogonal rounded, tree and lateral; for selected connectors or all connectors on the diagram.
• Connector route: the assistant routes the line through the given bend points and the points where it meets the element edges, for example following a sketch in a screenshot.
• Hiding connectors on a single diagram (and showing them again): the relationship stays in the model and on other diagrams, so you can declutter a dense diagram without deleting relationships.

Package copy and baseline

• Package copy creates a duplicate of the package with all its contents.
• A baseline is a saved version of a package in EA. Before deleting or substantially restructuring an existing package, the assistant is instructed to create a baseline, but this is not enforced: for important packages, ask for a baseline explicitly and use the ask mode.
• Restoring is done in Enterprise Architect: right-click the package, choose Manage Baselines, select the baseline and use Compare/Restore. The assistant does not restore baselines itself, because restoring through automation makes EA hang.

EA project glossary

The assistant adds terms to the EA project glossary (Project Glossary): a term with its meaning and type, by default the type Slownik. A Polish term goes in with all its forms (singular and plural, from the nominative to the vocative), so EA highlights every form in notes. Add a term by asking in the conversation or from the message field: right-click a word and choose Add “…” to the EA project glossary. If the assistant does not know the meaning or the type of the term, it asks you.

Structured scenarios of elements

The assistant creates, changes and deletes structured scenarios of elements, for example of use cases. They appear in EA on the element's Scenarios tab, with steps performed by the actor or by the system.

Model quality check

With a single command the assistant checks a package together with its subpackages. The check is done by the program, not by the AI model, so nothing is guessed. Built-in checks:

• default and empty names (for example Class1, Activity 2),
• elements without a description,
• orphans (no relationships and on no diagram),
• duplicate names in a package and duplicate relationships,
• relationships of an element to itself and to non-existent elements,
• relationships that ArchiMate 3.2 does not allow (described below),
• empty packages and empty diagrams.

Every finding has a severity: error, warning or info. The assistant makes fixes only after you agree.

Organization rules. You write your own rules in the file governance.json, placed next to app.properties (the settings file in the user data folder). When there is no such file and Compass is connected to a team hub, the rules come from the team policy (chapter 22). Example:

{"naming":[{"applies_to":"Component","pattern":"*Service","message":"A component name ends with Service"}],
 "required_tags":[{"applies_to":"«ArchiMate_ApplicationComponent»","tag":"Owner"}],
 "allowed_relations":[{"connector_type":"Realisation","source":"Component","target":"Interface"}]}

• naming: names of elements of the given type must match the pattern (pattern); message is the text of the finding.
• required_tags: an element of the given type must have the given tagged value.
• allowed_relations: a relationship type listed here is allowed only between the listed ends; relationship types that are not listed are not restricted.

In applies_to you give an element type or a «stereotype»; the wildcards * and ? work.

ArchiMate 3.2 relationships. When a relationship and both its ends have ArchiMate stereotypes (for example «ArchiMate_ApplicationComponent», «ArchiMate_DataObject»), the check also applies the relationship rules of ArchiMate 3.2, with no setup. It reports only certain violations, as errors; combinations that a derived relationship can make valid are not reported. For example:

• an access relationship must end at a passive structure element (business object, data object, artifact…) and start at a behaviour or active structure element,
• an influence relationship must end at a motivation element,
• triggering, flow and serving relationships do not connect passive structure or motivation elements,
• an assignment goes from active structure to behaviour (or from a node to an artifact),
• a specialization connects two elements of the same type,
• a motivation element realizes only another motivation element.

Junctions and groupings are not checked. The live check in Compass in EA (chapter 10) uses the same rules. To switch the ArchiMate rules off, put "archimate": false in governance.json.

As-is / to-be gap analysis

The assistant compares two packages, for example the current and the target state, and reports what is new, what is to retire and what has changed (stereotype, description, relationships). You can save the result to Excel.

Requirements chain: model, code, tests, issues

When you compare requirements with the model (section 8.5) and also give a source folder, the assistant (the tool trace_requirements) follows every requirement further: requirement → model element → code → test → issue keys. It reads the folder read-only.

• Code: files that declare a type named like the traced model element, and source files that name the requirement identifier.
• Tests: test files (in a test folder or named like OrderTest.java, order.spec.ts, test_order.py) that name the requirement identifier or are about a type of that code.
• Issues: keys such as ARCH-123 in the requirement and in the traced elements (name, alias, notes, tagged values).

Every requirement gets a status: complete, or broken: not in the model, no code or no tests.

CMDB and the model

The assistant compares the configuration items of a CMDB with the model (the tool cmdb_compare). It only reads: nothing is written to the model or to the CMDB.

• Data: a CSV or JSON export, for example a ServiceNow list export or the JSON of its Table API ({"result": [...]}), given as a path or an attachment, or the data an MCP server of the CMDB returned in the conversation. Columns such as name, sys_id, class, owner (owned_by) and status (install_status) are recognized by their headers.
• Matching: by the CMDB id kept in a tagged value of the element (sys_id or CMDB id), otherwise by name.
• Elements: by default components, nodes, devices, execution environments and ArchiMate application components, nodes, system software and services. You can name other types or stereotypes and limit the comparison to a package.
• Report: only in the CMDB, only in the model, and a different owner (tagged value Owner) or status.

The second prompt needs an MCP server of ServiceNow on the MCP servers card (see “Your own MCP servers” below). On request, the assistant adds missing elements, owners or ids to the model (with your approval) or saves the report to Excel. In a pipeline, the same comparison runs with --cmdb (chapter 23).

Jira issues

Once the Jira card is filled in (chapter 5), the assistant reads issues by key or by JQL search and uses them as context: it draws diagrams from the description of an issue (a story) or checks whether the model covers its requirements. Always with your consent in the approval panel it creates issues, adds comments and links to model elements.

Verification of a save

After every save, Compass reads the model again and compares it with the request: whether the created objects exist, whether new relationships have the asked ends, whether new elements are in the asked package, whether changed names, notes, stereotypes and tagged values have the new values, and whether deleted objects are gone. Differences are given to the assistant, which must report them instead of saying “done”.

Saves are all or nothing: if a save fails halfway, the objects it already created are deleted again. Deleting an element that has relationships always asks for your consent (also in auto mode), and the approval panel lists those relationships.

Always asked, with full details. Writing files (XMI export, documents from EA document templates) and importing XMI always ask for your consent, also in auto mode, and the panel shows the full path. Only full paths on a local drive are accepted: network shares and system, program and application-data folders are refused. An id must be a number. Saving a note to the assistant's memory, saving a document template and saving or running an EA script also always ask, with the whole text or code shown (texts longer than 20 000 characters are refused); a script runs exactly as shown, together with its !INC includes. When the assistant wants to read a file that is not an attachment of the conversation (a requirements document, a source folder), it asks you first.

Your own MCP servers

Your own MCP servers give the assistant extra tools, for example a ticket system, a repository or a company knowledge base. You list the servers in the file mcp_servers.json next to the settings file and test them in the MCP servers card. A server can be a local program (command and args, talking over stdio) or an HTTP service (url and headers, Streamable HTTP):

{"servers":[{"name":"hub","url":"http://127.0.0.1:8730/mcp","headers":{"Authorization":"Bearer ${secret:hub_token}"}},
 {"name":"files","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","C:/docs"]}]}

• ${secret:NAME} is an entry in the Windows Credential Manager and ${env:NAME} is an environment variable, so tokens do not have to lie in the file.
• Every tool call asks for your consent, unless the server has "trusted": true. Set it only for servers you trust: the server's own claim that a tool only reads is not enough.
• Compass's own keys and passwords (the AI provider keys, the database, EA, Confluence, Jira and Miro passwords and tokens) cannot be used in ${secret:…}. The only exception is ${secret:hub_token} in the headers of the team hub's own MCP endpoint (the hub address from Settings with the path /mcp), as in the example above. Save the tokens of other servers under their own names in Windows Credential Manager.
• A local program (command) gets only the basic Windows environment variables (PATH, TEMP, the user profile folders, the proxy settings…) and the variables listed in its "env".
• "command": "npx" works: Compass starts npx.cmd (likewise npm, pnpm and yarn). Servers started with npx need Node.js on the computer.
• The button Save and test MCP servers connects to each server and shows the number of its tools.

Ready-made servers. On the MCP servers card, choose a server in Add a ready-made server and click Add: its entry goes into the text of mcp_servers.json, where you complete it and save the card. A name that is already used gets a number.

Token for an MCP server. Type a name that starts with mcp_ (letters, digits and _, for example mcp_github) and the token, then click Save and test MCP servers. The token is saved in Windows Credential Manager; in mcp_servers.json you use it as ${secret:mcp_github}.

EA scripts

The assistant lists the script groups and scripts of the model, reads a script, saves a script (JScript, VBScript or JavaScript; a missing group is created) and runs it. Saving and running a script need your consent every time, also in auto mode, because a script can change anything in the model; the approval panel shows the whole code. The script runs in the open EA window or, when there is none, in Compass's own background EA session. Repository and Session.Output work as in EA, and !INC Group.Script includes are resolved from the model. If another model is open in EA, the run stops with a message.

More model operations

• Automatic diagram layout: direction down, right, up or left, and spacing.
• XMI: export of a package to an XMI file and import of a package from a file (import replaces GUIDs unless you ask to keep them).
• Linked documents of elements, created from text.
• Swimlanes of a diagram.
• Reversing a relationship (swapping its ends).
• Editing a package: name, notes, version, status and stereotype.
• A document from an EA document template (DOCX, PDF or RTF), for example the template “Model Report”, like Publish → Report Builder in EA.

Spelling in the language of Compass

The assistant tool spell_check checks the notes of elements and diagrams, scenario steps and the project glossary with the Windows spelling dictionary of the Compass language (EA's own spell checker has only English dictionaries). Names of elements and glossary terms count as known words. The assistant gives suggestions and corrects only after your consent. If Windows has no dictionary for the language, add the language in Windows Settings → Time & language → Language. In Compass in EA, the notes of a changed element are checked live (lines “✎ Spelling: …” in System Output, chapter 10).

Good to know

• The first EA call takes from a few to over ten seconds, because the application starts Enterprise Architect in the background and opens the model. Subsequent saves and diagram retrievals take less than a second. After 10 minutes without calls, the background EA closes and releases the license. Closing the application also closes its EA session. Compass in EA (chapter 10) does not start EA in the background: it saves through your EA window.
• Locks. When the option “The model requires a lock to edit” is on in the Model card, the assistant locks an object under its own account while saving and releases the lock afterwards. It will not change an object locked by another user; the message states who holds the lock on the element (account or group, since when), its package and diagram.
• Deletion is permanent. Deleting a package deletes all its contents. With important models, use the ask mode (chapter 16), use baselines and back up the database.
• All-or-nothing saves. When one operation of a save fails, the objects created earlier by that save are deleted again, so nothing half-done is left in the model; the message gives the cause.
• Check the result. The assistant can make mistakes: misread a photo, choose a different element type or lay out a diagram illegibly. Ask it to show the diagram after the changes and to make corrections.
• Large diagrams are saved by the assistant in several steps. This is normal.

8. Use cases

This chapter collects example prompts by goal. They were tried on a sample model with a package “Shop domain”, a process “Order process” and a diagram “Domain model”; in your own model, use the names of your own packages, diagrams and elements. The assistant does not need exact wording: what matters are the object names and what you expect. The details of the features are in chapter 7, and the rules for approving changes are in chapter 16.

8.1 Asking about the model

Reading the model changes nothing and needs no approval. Compass reads the model through the database or the EA file, and the assistant answers from that, naming objects with their name, package and GUID. Impact analysis follows relationships deep into the model and also gives the diagrams on which the affected elements lie.

What you see: the steps card with the model reads, then the answer in the chat. For an impact question, each element comes with the relationship through which the impact arrives, the path from the starting element and the list of diagrams. No approval window appears.

Tip: add “give the result in Excel” if the list is long: you get a workbook instead of text in the chat.

8.2 Creating and changing the model

The assistant creates packages, diagrams, elements and relationships and changes existing ones: names, notes, tagged values, position on a diagram. It saves to EA only after your approval (in ask mode before every save, in plan mode before the first save of an answer; chapter 16).

What you see: above the message field the “The assistant wants to save changes to the model” panel with a description of the changes and a “Before → after:” part: what is created, what changes from which value to which (field: old → new value) and what is deleted. For the third prompt you see the change for every class there. Approve saves the changes; Reject changes nothing and lets you tell the assistant what to do differently.

• Verification after every save. Compass reads the model again and compares it with the request (do the objects exist, do the relationships have the asked ends, are the new values stored). The assistant reports only what the model confirms, and reports differences instead of saying “done”.
• All or nothing. If a save fails halfway, the objects it has already created are deleted again.
• Deleting an element that has relationships always asks for consent, also in auto mode, and the panel lists those relationships.

Tip: for a bulk change like the third prompt, read “Before → after” before you approve: every change is visible there.

8.3 Undoing changes

Every save by the assistant goes into an undo journal (the “time machine”) together with the operations that reverse it. Undoing deletes the objects that were created and gives changed fields, tagged values, positions and moves their previous values. It applies to the assistant's saves in this model; changes you made by hand in EA are not included.

What you see: for the history, a list of saves, newest first, with what can be undone. For an undo, an approval panel “Undo the latest saves of the assistant (…)” listing the saves (it appears in every mode); after approval Compass undoes the saves and checks the result in the model. If there is nothing to undo, the assistant says that there is nothing to undo in this model.

Deletions, imports and automatic diagram layout cannot be reversed by operations. Before such a save Compass makes an EA baseline of the affected package. You restore it in Enterprise Architect: right-click the package, choose Manage Baselines, select the baseline and use Compare/Restore.

Tip: you can undo several saves at once (“Undo the last three changes”); ask for the history first to see what the undo will include.

8.4 Model quality and team rules

The quality check is done by the program, not by the AI model, so nothing is guessed: default and empty names, elements without a description, orphaned elements, duplicates, relationships to non-existent elements, relationships not allowed in ArchiMate 3.2, empty packages and diagrams, and the rules from the governance.json file (or from the team policy in the hub). Spelling of notes is checked with the Windows dictionary of the Compass language.

An example of a short governance.json file (it lies next to app.properties) that requires the tagged value Owner on every class:

{"required_tags":[{"applies_to":"Class","tag":"Owner"}]}

What you see: a summary of the check and findings with a severity: error, warning or info. For spelling: the number of texts and words checked and a list of possible mistakes with suggestions. An approval window appears only when you ask for corrections. If Windows has no dictionary for the Compass language, add the language in Windows Settings → Time & language → Language.

Tip: after the check, ask for one group of findings to be fixed at a time, for example “Fill in the missing descriptions of the classes in the Shop domain package”. The save goes through the usual approval and verification.

8.5 A requirements document against the model

The assistant reads requirements from a document (Word .docx, .txt, .md, an attachment of the conversation, a Confluence page by ID or pasted text) and compares them with the model. A requirement is a line or table row that starts with an identifier, for example W1, R.1.2, REQ-12, FR-01. The matching is done by the program: it looks for elements carrying that identifier (in the name, alias, notes, tagged values), trace relationships and similar words. The assistant judges the candidates.

What you see: for a file that is not an attachment of the conversation, first a question whether the assistant may read it; then a summary “Traceability: … requirements – covered …, only candidates …, NOT covered …, id matches but content differs …” and a list of requirements with one of four statuses: covered, candidates, NOT COVERED or ID MATCHES, CONTENT DIFFERS. A separate list is “Model elements no requirement refers to”. The assistant also points out requirements that contradict the model. You get the Excel matrix as a file card with the Open and Save as… buttons. Trace relationships (Realisation or Dependency «trace») are created only after your consent, in the usual approval panel.

Tip: a Confluence page can be read once the Confluence card in Settings is filled in (chapter 5). Matching is most reliable when the requirement identifier is written in the name, alias, note or tagged value of the element; without it only candidates remain. You can narrow the scope to a package: “…with the Shop domain package”. Add a source folder to follow the requirements on to the code, tests and issues (chapter 7, “Requirements chain”).

8.6 The model against the code

The assistant reads a code folder (for example a local clone of a repository) read-only and compares it with the model: classes, interfaces, enums and records with their fields (Java, Kotlin, C#, TypeScript, Rust, Python), tables and columns from SQL (CREATE TABLE) and API operations (operationId from OpenAPI) against the classes, attributes, tables and operations in the model.

What you see: first a question whether the assistant may read the folder, then a summary “Model ↔ code: … source files” and the sections In the code, not in the model, In the model, not in the code, Different fields (code vs model attributes), Database tables and API operations (OpenAPI operationId) not in the model. No approval for a save appears, because nothing is written: neither to the code nor to the model.

Tip: limit the comparison to one package (“…with the Shop domain package”) if the folder holds many services, and ask for a report in Excel. Adding the missing classes to the model is a separate request that goes through the usual approval.

8.7 Estimating a change

From the impact of a change in the model, the assistant builds a first estimate: the elements to change, the related elements to adapt, the further ones to check and the diagrams to update become WBS rows in plain functional language, with hours depending on the element type. Tests, analysis and documentation and a risk buffer are added.

What you see: a WBS table with rows such as “Change: Product”, “Adapt: …”, “Check the impact on: …”, “Update the diagram: …”, “Tests of the change”, “Analysis and documentation” and “Risk buffer”, a total in hours and person-days, “Hours by type” and “Risks” (for example an element with many relationships, without a description, or a change touching many packages). The Excel file is a file card with the Open and Save as… buttons.

Tip: this is a starting point taken from the model, not an offer: adjust the hours with the team's knowledge. The hour norms are in the estimate.json file next to the settings file; when it is missing, default norms apply.

8.8 Documents and exports

The assistant prepares Word documents from the model and its diagrams (chapter 13). Enterprise Architect also generates a report from its own EA document template (DOCX, PDF or RTF) and exports packages to XMI. The report and the XMI export always ask for your consent, also in auto mode.

What you see: for the Word document, a file card with the Open and Save as… buttons. For the report and XMI, an approval panel with a description (“documents from EA templates”, “packages exported to XMI”) and the full path of the file, and after the save a message “Report saved: …” or “XMI saved: …” with the path; Compass checks that the file was created.

Tip: the report must have the extension .docx, .pdf or .rtf, and the XMI file .xml or .xmi. Give a full path on a local drive: network shares and system, program and application-data folders are refused. A template with the given name must exist in EA; if it does not, EA creates no report and the assistant says so.

8.9 Diagrams

Besides drawing new diagrams, the assistant improves existing ones: it lays them out automatically (down, right, up or left, with a given spacing), adds swimlanes and creates linked documents of elements from a given text.

What you see: the usual approval panel with a description of the change, and after the save the verification of the model. If the same model is open in EA, the changed diagram refreshes in your window by itself (chapter 9).

Tip: after the change ask “Show the Domain model diagram”: you see it as an image in the chat and can judge whether the layout is readable. An automatic layout cannot be reversed by operations, so Compass makes a baseline of the package first (section 8.3).

8.10 EA scripts

The assistant writes EA scripts (JScript, VBScript or JavaScript) and runs them in the model: they list data, check something or change many objects at once. A missing script group is created automatically. The script runs in the open EA window or, when there is none, in a separate background EA session.

What you see: first an approval panel for saving the script (group, name, language and the whole code), then a separate question about running it: both appear every time, also in auto mode, because a script can change anything in the model. The script runs exactly as shown, together with its !INC includes. The output (what the script wrote through Session.Output) goes to the chat as “Output of the script …”. If another model is open in EA, the run ends with a message.

Tip: before you approve the run, read the script code in the approval window, especially when the script is meant to change something. Start with read-only scripts.

8.11 Jira and Confluence

Once the Jira and Confluence cards in Settings are filled in (chapter 5), the assistant reads issues and pages as context: it checks which model elements an issue concerns, draws diagrams from its description or compares the requirements of a page with the model (section 8.5).

What you see: when reading, the issue read in the steps card and an answer with a list of elements. Creating issues, comments and links to model elements always needs your consent in the approval panel, in every mode. Publishing a page to Confluence also always asks and says plainly when it will replace an existing page (chapter 13).

Tip: give the issue key and the package name. When you do not name a project, a new issue is created in the default project from the Jira card.

8.12 Working as a team (Compass Hub)

With a team hub (chapter 22; the Team (Compass Hub) card in Settings) you can first propose a change of the model to the team: the assistant saves nothing in the model, it only sends the hub a change set with a description and a “before → after” preview. The team comments on it in the web view, and an architect or administrator approves or rejects it. Nobody, not even an administrator, can approve their own change set. You apply an approved change set in Compass.

What you see: after the proposal a message “Change set for the team: …” with its number (CH-…), and in the hub's web view a new row in the Change sets tab. When applying: the usual approval panel and verification after the save; the hub marks the change set as applied. Only an approved change set that belongs to this model can be applied, and only once: Compass first claims it in the hub and reports the result after the save.

Web view. People without Enterprise Architect sign in to it with a user name and a password from the hub administrator (address https://<hub>/; http:// only on the same computer). The tabs are: Ask (questions about the model), Search (finding elements), Model check (model check by the team's rules), Gaps (as-is / to-be gaps), Audit trail (the team audit trail), Team notes (shared notes) and Change sets (proposed changes with comments and a decision). In the Ask tab you type a question in your own words, for example “Which systems use the payment gateway?”. The assistant there only reads the model: it has no access to files, Jira, Confluence or MCP servers and cannot propose or save anything. It answers one question at a time (a question is at most 2000 characters long), and the questions go into the hub's audit trail.

Tip: give the proposal a title from which the reviewer can tell the scope of the change without opening the details. A change set belongs to a model: you can apply it only in a Compass connected to the same hub model.

8.13 Extra tools from MCP servers

Your own MCP servers give the assistant extra tools: a ticket system, a repository, a knowledge base or the MCP server of the hub itself. You list the servers in the mcp_servers.json file (chapter 7) or add a ready-made one (Azure DevOps, GitHub, ServiceNow / CMDB, Files, Compass Hub), and check them in Settings, on the MCP servers card, with the Save and test MCP servers button.

What you see: in the steps card the call of the server's tool, then its result in the answer. Every tool call asks for your consent, unless the server has "trusted": true; set it only for servers you trust.

Tip: name the server from mcp_servers.json in the prompt (“through the MCP server hub…”) so that the assistant knows which one to use. Keep tokens in the Windows Credential Manager under their own names (${secret:name}), not in the file; Compass's own keys and passwords cannot be used there (chapter 7).

8.14 Compass inside Enterprise Architect

When Compass is docked in EA (chapter 10), it watches the model while you work and needs no prompt. The results go to the Loonar Compass tab of the System Output window:

• Live check: after you draw a relationship and after you edit an element (name, stereotype, tagged values), a “⚠ Model check: …” line appears, by the same rules as in section 8.4.
• Spelling: the notes of a changed element are checked in the language of Compass and give “✎ Spelling: …”.
• Event agents: your own rules in the event_agents.json file (the Event agents (Compass in EA) card) start the assistant after an event in EA. Its remarks start with 🤖.

An example rule that checks the owner and the description after a component is created:

{"agents":[{"name":"Component owner","event":"element_created","applies_to":"Component",
  "prompt":"Check that the new component has an owner and a description; suggest what to fill in."}]}

What you see: in System Output a line such as “🤖 Component owner: …” with the assistant's remarks. The agent only reads the model: it has no access to files, Jira, Confluence or MCP servers and cannot propose or save anything. The same agent reacts to the same object at most once a minute. A new element is checked only after its first edit, because EA first gives it the name Class1.

Tip: write short, concrete agent prompts and narrow them with applies_to (a type, a «stereotype» or *). After changing the file, click Save event agents.

8.15 Checking the model in a CI pipeline

Check mode runs the model check, the comparison with the code and with the CMDB, and the requirements chain without the window and without the AI model, and ends with an exit code that a pipeline understands (chapter 23).

LoonarCompass.exe --check --model model\shop.qea --rules governance.json --code src --requirements docs\requirements.md --junit junit.xml --fail-on error | Out-Host

What you see: a Markdown report on the standard output that starts with the result, PASSED or FAILED, followed by the sections of the model check, the model and the code, and the requirements. In the pipeline, the JUnit file shows each group of findings as a test, failed when it is at or above --fail-on. The exit code is 0 when the check passed, 1 when there are such findings, and 2 for wrong arguments or a model that cannot be read.

Tip: start with --fail-on error and keep the warnings in the report; switch to warning when the model is clean. Keep governance.json in the repository and pass it with --rules, so that the pipeline and the people use the same rules.

8.16 Comparing the CMDB with the model

The assistant compares the configuration items of a CMDB (an export or the data of an MCP server) with the components of the model and shows what is missing on either side and where the owner or the status differs (chapter 7, “CMDB and the model”).

What you see: for a file that is not an attachment of the conversation, first a question whether the assistant may read it; with a ServiceNow MCP server, the call of its tool (it asks for your consent unless the server is trusted). Then a summary “CMDB ↔ model: … configuration items, … elements of the model, matched …” and the sections In the CMDB, not in the model, In the model, not in the CMDB and Different owner or status. Nothing is saved without your approval.

Tip: keep the CMDB id (sys_id) in a tagged value of the elements: then renamed items still match. Limit the comparison to a package or name the element types when the model holds more than the CMDB does.

8.17 Jira issues and Confluence pages from the hub

When the administrator has set up integrations in hub.json (chapter 22), architects and admins create Jira issues and Confluence pages straight from the hub's web view, without Compass and without EA. The hub uses its own service account.

• Search → click an element → Create Jira issue: type the summary; the issue gets the details of the element.
• Change sets → open a change set → Create Jira issue for this change set: one issue per change set.
• Pick a package in the tree → Model check → Publish this package to Confluence: type the title (empty: the package and model name).

What you see: “Created ARCH-…” with the link to the issue; in the change set a line “Jira: ARCH-…”; for Confluence “Created:” or “Updated:” with a link to the page. Each action is recorded in the Audit trail tab under your name.

Tip: the Confluence page is a text summary of the package (elements with their descriptions and relationships, without diagrams) and is replaced at every publication: edit the model, not the page. For a page with diagrams, publish from Compass (chapter 13).

Tips for good prompts

• Name packages and diagrams exactly, as they are in the model (preferably in quotation marks). If two objects have the same name, add the package.
• Say whether to change or only propose. “Propose, but do not save yet” gives a description of the changes without saving.
• For a larger change, ask for a preview first and work in plan mode: the approval panel shows the whole “Before → after” before the first save.
• Ask for the result to be saved to Excel or Word when it has to live outside the chat: lists, matrices and estimates.
• For risky changes use the ask mode (Settings → “Language and change approval”), ask for a baseline of the package and check the diagram after the changes.

9. Working with the open EA window

If you have the same model open in Enterprise Architect, the assistant works together with your EA window:

• it knows what you have open and selected: which diagram is open and which elements are selected on the diagram or in the Project Browser. So you can write “this element” or “the selected tasks”,
• it opens diagrams in your EA window and highlights elements in the Project Browser,
• after saving, it refreshes the changed diagrams and packages in your window by itself, without pressing F5.

Only when the EA window is not open or shows a different model does the assistant work without it; you will then see the changes after refreshing the package in EA (F5). The connection string of your EA window is never sent to the model.

The cooperation described here applies to the separate application. Compass started in Enterprise Architect itself always works with the project open in its EA window (chapter 10).

Reads of an EA file that is open in an EA window go through that window, because the file on disk may not have your latest changes yet.

10. Compass in Enterprise Architect

Loonar Compass also runs inside Enterprise Architect, as a window docked next to the Project Browser and the diagrams. You work in it as in the separate application: the conversation, attachments, change approval, memory, templates and documents work the same way. The separate application, started from the Start menu, keeps working as before.

Installing and starting

1. In the installer, on the “Destination folder” page, select “Add Loonar Compass to Enterprise Architect”. It works with any Enterprise Architect installation, also a trial. Restart EA after the installation.
2. Open a project in Enterprise Architect: a file or a database.
3. On the Start ribbon, in the Add-Ins group, click Loonar Compass (you also find the button under Specialize). The button works only with a project open.
4. Compass opens as a docked window in EA, in the same place as the Properties window. You can drag it elsewhere, float it or add it to a tab group; EA remembers where you put it.

Project and conversations

• In EA, Compass always works with the project open in that EA window: a file or any database. It reads the model through Enterprise Architect itself, so it needs no model settings, no passwords and no choice of a conversation model. Opening another project in EA switches Compass to it; without an open project, Compass does not work.
• You choose conversations from the drop-down at the top of the window. The list shows only the conversations with this project. The + button starts a new conversation, and the pencil renames the selected one.
• The view icons are at the bottom of the window; in a narrow window the pages scroll sideways and up and down.
• Ctrl + V pastes pictures, files and text, as in the separate application.
• The settings in EA have no Model and Enterprise Architect cards. The AI model, Language and change approval, Confluence, Miro, Jira and Team (Compass Hub) cards work as in the separate application (chapter 5).

Changes, diagrams and references to objects

• Writes go through the same EA window, so changes show at once in the Project Browser and on diagrams. Change approval works as in the separate application (chapter 16).
• Show diagram and Edit diagram open the diagram in EA itself instead of showing an image in the chat.
• Right-click an element, package or diagram (in the Project Browser or on a diagram) and choose Specialize → Add to the Compass conversation. A reference to the object goes into the message, for example «Package: Shop (id 5)», so the assistant knows which object you mean.

Live check

When Compass is docked in EA, it checks changes while you work, by the same rules as the model check (built-in ones and those from governance.json or the hub). The check starts after you draw a relationship and after you edit an element (name, stereotype, tagged values). The findings appear in the Loonar Compass tab of the System Output window, each only once, as “⚠ Model check: …”. A new element is checked only after its first edit, because EA first names it Class1.

Event agents

The card Event agents (Compass in EA) holds rules by which the assistant reacts to what happens in EA. The rules are in the file event_agents.json:

{"agents":[{"name":"Component owner","event":"element_created","applies_to":"Component",
  "prompt":"Check that the new component has an owner and a description; suggest what to fill in."}]}

• Events (event): element_created, element_changed, connector_created, diagram_created. In applies_to give an element type, «stereotype» or * (the wildcards * and ? work).
• Agents work while Compass is open in its tab in EA. The assistant reads the model and answers in the Loonar Compass tab of System Output (lines start with 🤖). It only reads the model: it has no access to files, Jira, Confluence or MCP servers and cannot propose or save anything.
• The same agent reacts to the same object at most once a minute.
• The button Save event agents saves the rules and shows the number of agents.

Live spelling. The notes of a changed element are checked in the language of Compass; remarks appear in System Output as “✎ Spelling: …”.

The assistant's steps in System Output

EA's System Output window has a Loonar Compass tab: your messages and every step of the assistant (model reads, writes to EA, results) with the time. Meanwhile, the chat in the Compass window shows only the last step, in one line.

Closing. Compass closes together with Enterprise Architect and saves the conversation. When you close the project in EA, Compass asks you to open a project.

11. Diagram editor

Every EA diagram shown in the chat has an Edit diagram button. It opens the diagram in an editor window where you change it with the mouse. The editor works on the model, not on a picture: what you save goes into EA through the same operations the assistant uses, with the approval panel and the change log (chapter 16). The editor needs WebView2, which is part of Windows 10 and 11. In Compass in EA, the Edit diagram button opens the diagram in Enterprise Architect itself (chapter 10).

Drawing

• Move, resize and align elements with the mouse and the alignment buttons; Ctrl+Z and Ctrl+Y undo and redo.
• Add: the buttons depend on the kind of diagram (class, component, use case, activity, BPMN, state machine, deployment, package, sequence). A new element goes to a free spot near the middle of the view; type its name straight away.
• Connect: drag from one element to another. The kind of relationship comes from the Connector list.
• From the model… puts an element that already exists in the model on the diagram (search by name, type or package). Its relationships with the elements of the diagram appear after saving.
• Double-click an element or a relationship to rename it.

Properties

The Properties panel shows the selected element or relationship. Each field is marked model (the change applies everywhere the object is shown) or diagram (only this diagram).

• General: name, alias, stereotype, keywords, status, version, author, phase, complexity, abstract and notes; the package, GUID and dates are read-only. For a relationship: name, stereotype, direction, the multiplicities and roles of both ends, notes.
• Attributes and operations (classes, interfaces, components): add, change (visibility, name, type) and delete; a new operation takes its parameters as name: Type, other: Type.
• Tagged values: change, add and remove; where the profile lists the allowed values (for example BPMN task types), you choose from a list.
• Appearance: the fill color on this diagram or the element's default color, and the line style of a relationship on this diagram.

Deleting

The Delete key removes what you have added in the editor without asking. For an object that is already in the model, the editor asks: Remove from this diagram (it stays in the model and on other diagrams) or Delete from the model (permanently, with its relationships, from every diagram). It shows on which other diagrams the element is and how many relationships it has.

Sequence diagrams

Lifelines have a header and a dashed line; they move only sideways. Messages go from top to bottom in their order, with their numbers, as EA draws them. Change the order of the selected message with ▲ ▼ in the panel or Alt+↑ / Alt+↓. A new message (drag from one lifeline to another) goes right after the selected one. In the panel you set the kind (synchronous or asynchronous), whether it is a reply, and you can name it after an operation of the receiver.

Saving

• Save to EA saves the changes and closes the editor; the result appears in the conversation. Cancel closes it without saving.
• Tidy with AI saves the changes and asks the assistant in the conversation to arrange the diagram so it reads well, without adding, deleting or renaming anything.

12. Sending diagrams to Miro

A diagram from EA can go to a Miro board as editable shapes and connectors in a frame with the diagram's name. Only from EA to Miro: what people change on the board does not come back to the model.

Setup, once:

1. In Miro, open the settings of your profile → Your apps → Create new app. Miro first asks you to create a Developer team (a free sandbox for your apps); accept its terms and create it. In an organization on the Enterprise plan, the organization's admin sets it up.
2. Give the app a name (for example Loonar Compass) and leave “Expire user authorization token” unchecked: an expiring token stops working after an hour.
3. Under Permissions, select boards:read and boards:write.
4. Click Install app and get OAuth token and choose the organization and team whose boards the application may use (for a first test, the Developer team). Copy the token.
5. Paste it in Settings, card “Miro”, and click Save and test Miro connection. The token is kept in Windows Credential Manager.

Diagrams can go only to boards of the team the app is installed in; to use another organization, install the app there too (the same button).

Sending:

1. Click Send to Miro under a diagram in the chat.
2. Choose the board (the one you used last time is offered first; the search field filters by name).
3. The thumbnail shows what is already on the board (grey) and where the diagram will go (a blue frame, red when it would cover something). The application finds a free spot by itself; drag the frame to choose another one.
4. Click Send to Miro. When it is done, the conversation gets a message with a link that opens the board at the new frame.

Sequence diagrams go as lifelines with numbered messages in their EA order (replies dashed). Sending the same diagram again puts a new frame next to the earlier one, so nothing changed on the board is overwritten.

13. Documents: Word, Excel, images, Confluence

The assistant prepares documents from the content of the model and the conversation. The finished file appears in the chat as a card with buttons.

Confluence pages

The assistant prepares a page in the Confluence source editor format (storage XHTML): headings, tables, lists, a table of contents, panels (info, note, warning, tip, expand section), statuses, Jira issues, user mentions and code blocks. Diagrams from EA and images are added as attachments. The page code is saved in the attachments folder, and the page images in a folder next to it (<page>_images).

Pasting manually (without Confluence settings):

1. Click Copy page code on the page card.
2. In Confluence, open the page for editing, open the Source Editor, paste the code and confirm.
3. Click Open images folder and add the images to the page as attachments.

Publishing through the assistant. Once you have filled in the “Confluence” card, the assistant publishes the page via the REST API at your request: it creates a new page under the parent page or updates an existing one (given by ID or title). Images are uploaded as attachments; existing ones get a new version. Diagrams are exported from EA anew on every publication, so republishing refreshes the page after changes in the model. The assistant remembers the pages it has published. The connection uses HTTPS only (http:// is accepted only for a server on the same computer).

Confluence Cloud: where the details come from.

1. Token: it is created on your Atlassian account, not in Confluence. Open https://id.atlassian.com/manage-profile/security/api-tokens (Atlassian account → Security → API tokens). Atlassian may first ask you to confirm it is you with a code sent to your email.
2. Click Create API token (the plain one, not Create API token with scopes), give it a name, for example Loonar Compass, and choose how long it is valid: one week by default, at most one year. Click Create and copy the token: Atlassian shows it only once. When it expires, create a new one and paste it on the “Confluence” card.
3. Email: the email address of the Atlassian account the token belongs to.
4. Address: your site with /wiki, for example https://your-site.atlassian.net/wiki.
5. Space key: it is in the address of any page of the space, after /spaces/ (for example …/wiki/spaces/PM/… gives PM), and under Space settings.
6. Parent page ID (optional): the number in the address of the page, after /pages/ (for example …/pages/65818/… gives 65818).

Save the card with the Save and test Confluence connection button.

14. Document templates

A template tells the assistant how to build a document: which sections it should have and what to put in them. The assistant fills it with content from the model and prepares a Confluence page or a Word document.

After installation, the following default templates are available:

• Preliminary feasibility analysis,
• BRD - Business requirements,
• System change description,
• Process description.

The “Document templates” view

• A list of templates with a short description.
• Use inserts into the chat a request to prepare a document based on the template. Complete it (for example with the name of a package or process) and send it.
• Edit opens the template file in Notepad.
• Open templates folder opens the templates folder in Explorer (older installations may still use the szablony folder).

Your own templates

Templates are Markdown files with instructions for the assistant. The first line has the form > Template: description; the description is shown in the list. You can modify the existing templates, add your own files to the templates folder or ask the assistant to create a template from a sample document. The assistant always asks for your approval before it saves a template, also in auto mode, and shows its whole text.

15. Assistant memory

The assistant keeps notes between conversations: modeling conventions, your preferences, corrections and facts about projects. It knows them in every new conversation. A note on the same topic is updated instead of duplicated, and outdated ones are removed.

The assistant saves a note by itself when it learns something worth remembering, and tells you so in one sentence. You can also ask it explicitly, starting with “remember…”:

Notes are shared by all models. When you want a note to apply to one model only, say so, for example “remember this only for this model”: the note is then used only in conversations with that model, and the “Assistant memory” view shows which model it belongs to.

Saving a note always requires your approval, in every mode, and the approval panel shows its whole text. Saving a note does not interrupt the assistant's work on the current task. The whole content of the memory is sent to the AI model with every request (chapter 18).

The “Assistant memory” view

• A list of notes with dates.
• Remove next to a note deletes it.
• Open memory folder opens the memory folder in Explorer. The notes are Markdown files in it, and the index is in the MEMORY.md file.

16. Approving changes and the audit log

You set the mode in the Settings view, on the “Language and change approval” card. It decides whether and when the application asks for approval before saving to EA. Reading the model and showing diagrams never require approval. The current mode is also visible in the message card.

When approval is needed, a “The assistant wants to save changes to the model” panel appears above the message field, with a description of the changes (how many packages, diagrams, elements and connectors, and the names of the objects being deleted, moved or copied) and the Approve and Reject buttons. A rejected save does not change the model; the assistant is informed of the rejection and may suggest something else.

Publishing to Confluence always asks for approval, in every mode, and says when an existing page will be replaced (chapter 13). Also in every mode, Compass asks before: deleting an element that has relationships, undoing saves, creating Jira issues, comments and links, writing files (XMI export, documents from EA templates) and importing XMI, saving a memory note or a document template, saving or running an EA script, calling a tool of an MCP server that is not trusted, and reading a file that is not an attachment of the conversation (chapter 7).

In the approval panel the description of the changes has a “Before → after:” part: what is created (new objects), what changes from which value to which (field: old → new value) and what is deleted. So you see the effect of the save before you click Approve.

Deleting an element that has relationships. Deleting an element that has relationships always asks for your consent, also in auto mode. The approval panel lists those relationships.

Audit log

Every save by the assistant to the model, including failed ones, goes into the audit log (saves you rejected are not recorded, because nothing was saved). The Model audit log view shows the latest 200 entries, newest first: time, result, EA account, database and changes. The Export to Excel button saves the whole log as an XLSX workbook, for example for reviewing changes as a team, and Open log file opens the audit_log.jsonl file.

17. Conversations: history, search, background work

• New conversation: the + button above the list of conversations. Every conversation is saved and comes back after the application is restarted.
• Groups: conversations are grouped into “Today”, “Yesterday”, “Last 7 days” and “Earlier”.
• Search: the “Search conversations…” field filters the list by title and by message content.
• Renaming: click the pencil next to the selected conversation, type a name; Enter saves, Esc cancels.
• Model of the conversation: every conversation works with its own EA model, and a new conversation starts with confirming that model. The new conversation screen shows the default model from the settings. Choose another model… opens the “Model of this conversation” window, where you choose Default from the settings or Another model: a PostgreSQL database (server, port, database name, user, password, connection encryption) or an EA file (.qea, .qeax), with the EA account and security options as on the Model card. Test the connection opens the model, counts packages, elements and diagrams, and saves a test package in it, which it checks and deletes at once. Confirm the model and start fixes the model of the conversation: it cannot be changed afterwards, and the Model: … button in the header shows it view only. To work with another model, start a new conversation. Changing the default model in the settings does not change conversations in progress. Passwords of a connection that differs from the settings are kept in Windows Credential Manager. In Compass in EA, the model of the conversation is always the project open in EA (chapter 10).
• EA file dropped on the window: a .qea or .qeax file dropped on the chat becomes the model of the conversation instead of an attachment; in a conversation with messages, a new conversation starts with that file.
• Conversations from earlier versions get a copy of the model from the settings when version 0.5 or later starts for the first time, so they keep working with that model even if the settings change later. Hovering over a conversation in the list shows its model.
• Several conversations at once: while the assistant is working, you can start a new conversation or switch to another one. The work already started continues in the background.
• Deleting: conversations cannot be deleted in the application. If you need to, close the application and delete the conversation's file in the history folder (chapter 18).

Saves to EA from different conversations are carried out one after another, not simultaneously. EA in the background keeps one model open at a time: switching between conversations with different models reopens it, which takes from a few to about 25 seconds. When the chat is scrolled up, the circle with an arrow above the message field takes you to the end of the conversation.

18. Data, security and privacy

Where your data is

Conversation history is stored as plain files in your Windows profile, protected by your Windows account; the application does not encrypt it.

What is sent to the AI model provider

So that the assistant can answer, every request to the chosen AI model provider (Anthropic or OpenAI, AI model card) contains: the content of the conversation, the attached files, the full content of the assistant's memory, the list of templates with their descriptions, and what the assistant has read from the model in that conversation, i.e. the results of its database queries (names and descriptions of packages, elements, diagrams) and images of the diagrams shown. The whole database is not sent, only what the assistant asked for. After a language change, the content of the memory and templates to be translated is also sent. The data goes directly to the chosen provider (api.anthropic.com or api.openai.com) with your API key; the other provider receives nothing, and Loonar does not receive it.

The assistant's permissions

• The assistant reads the database in a read-only session, and a model file read-only, with a time limit for each query; server functions that read files or affect other sessions are blocked. All changes go through Enterprise Architect, under the model's EA account (from the Model card or from the model of the conversation), so the permissions and locks of that account apply to them. Compass in EA reads and writes the model through the EA window it is open in, under the account you logged in to EA with.
• In Confluence, the assistant works with the permissions of the token from the “Confluence” card and publishes only after your approval.
• The assistant has no access to files on disk other than those you attach to it yourself and its own memory and templates folders; it reads any other file (a requirements document, a source folder) only after asking you. Images drawn by the assistant cannot read files from disk or from the network.
• The assistant treats the content of attachments, documents and the model as data, not as instructions.
• The connection string of your open EA window, with its login details, is never sent to the model.

Connections and encryption

• The AI model API (Anthropic or OpenAI), Confluence and Miro are used over HTTPS only.
• The connection to the model database supports TLS (Model card, see “Database connection encryption” in chapter 5). Tip: administrators can enforce TLS for all clients with hostssl entries in pg_hba.conf. Enterprise Architect's own connection to the database follows EA's settings.
• The application uses the proxy from the Windows Internet settings and the HTTPS_PROXY and ALL_PROXY variables. Proxies with a PAC script and NTLM/Kerberos proxy authentication are not supported.
• Temporary errors of the AI model API (overload 529 or other 5xx errors, rate limit 429) are retried automatically.

19. Troubleshooting

20. Reporting bugs and new releases

Report a bug

1. Click the Report a bug icon in the navigation bar.
2. Enter a subject and a description: what you were doing, what you expected, what happened. The description is required.
3. Add images, for example screenshots: drag them into the window, paste them from the clipboard (Ctrl + V) or choose them from disk. The added images are shown as thumbnails; together they can take up to 15 MB. Remove personal and confidential data from the screenshots before sending.
4. Optionally, enter the email address to which I should reply. The option “Include technical information (application version, system, model, approval mode, last message; no passwords or keys)” is selected by default; clear it if you do not want to include this information.
5. Click Send report. A ready message to the author, with the images as attachments, opens in the Windows mail program. Check it and send it.

The report goes to Loonar Mariusz Głowacki and is used only to answer it and to improve the application; the details are in the privacy policy, linked from the form. The temporary copies of the images are deleted as soon as the mail program has taken them. If the mail program does not accept attachments from other applications, a message without images opens together with the folder containing the images: drag them into the message. Only in this case do the copies stay in that folder.

New releases (newsletter)

On the “New releases (newsletter)” card in the settings, enter your email address and select “I want to receive news about new releases”: a short email when a new version is released, with a description of the changes and where to download it, without ads. Your choice is stored in the settings, and subscribing and unsubscribing are sent to the author as a message from the mail program. Your address is used only for this news, based on your consent, until you withdraw it: clear the option and save, or write an email. The card links to the privacy policy.

22. Compass Hub (team service)

Compass Hub is an optional team service, run on a team computer or server. It provides a shared policy (model check rules and the minimum approval mode), a central audit trail of changes from all workstations, shared notes, change sets for review, a web view of the models for people without Enterprise Architect, Jira issues and Confluence pages created from the web view, and an MCP server (read-only) for other AI tools. Without a hub Compass works on its own, as before.

For the user

You get the hub address and your API token from the administrator (the Users tab of the web view). Enter them in the “Team (Compass Hub)” card in the Settings view: Hub address (it must start with https://; http:// only on this computer), Token and optionally This model in the hub (the source id, that is the hub's model that matches yours), then click Save and test hub connection. The test shows your account, role and the team policy. With a hub:

• the team policy min_approval can only make the local approval mode stricter (from the loosest: auto, plan, ask);
• the model check rules from the hub apply when there is no local governance.json (chapter 7);
• every saved change goes to the team audit trail; it is sent in the background, so a hub that is down does not stop your work, and the last problem is shown on the card.

Installing the hub

The hub is a program of its own, compass-hub, for Windows and Linux. It reads the models directly (a PostgreSQL database or .qea/.qeax files), so the server needs no Enterprise Architect. Downloads:

• Windows: CompassHub-0.8.2-windows-x64.zip with compass-hub.exe, an example hub.json and a README.
• Docker: the image ghcr.io/loonar-eu/compass-hub:0.8.2, or build it yourself in the root folder of the repository: docker build -f hub/Dockerfile -t compass-hub .

In a console (Windows or Linux). The hub runs until you close the console:

compass-hub hub.json

As a Windows service, in a console run as administrator. The service “CompassHub” starts at once and with Windows; you stop it in Services or with sc stop CompassHub, and remove it with --service-uninstall:

compass-hub --service-install C:\Hub\hub.json
compass-hub --service-uninstall

In Docker. Put hub.json with "listen": "0.0.0.0:8730" in the data folder, which the container sees as /data:

docker run -d --name compass-hub -p 8730:8730 -v /srv/compass-hub:/data \
  -e LOONAR_SECRET_CLAUDE_API_KEY=... ghcr.io/loonar-eu/compass-hub:0.8.2

• The container runs as the user with id 10001: the data folder must be writable by it, because the hub writes hub.json, the audit trail, notes, change sets and hub.log there.
• Models: .qea/.qeax files in the data folder, with paths as the container sees them (for example model.file=/data/models/shop.qea in the source's app.properties), or a PostgreSQL database.

LoonarCompass.exe --hub C:\Hub\hub.json still works: the desktop application then runs the hub without a window. The hub writes its log to hub.log next to hub.json. compass-hub --version prints the version.

Secrets of the hub

Keys, tokens and passwords are not kept in hub.json. compass-hub takes each of them from the environment variable LOONAR_SECRET_<NAME> or from the file named in LOONAR_SECRET_<NAME>_FILE (for example a Docker secret); on Windows also from Credential Manager of the account the hub runs under. For the Windows service, set them as system environment variables.

Accounts and sign-in

People sign in to the web view (https://<hub>/; http:// only on the same computer) with a user name and a password. Compass and MCP clients use an API token.

• A password has at least 10 characters and may not be the default password or the user name. The hub stores passwords only as PBKDF2 hashes.
• A sign-in lasts 12 hours; Sign out ends it at once.
• After 20 wrong passwords or tokens from one address, that address is refused for 10 minutes.
• Sign in with a token instead on the sign-in page lets you sign in with an API token.

The Users tab (admins only):

• Add a user: the name, the role and a first password, which the user must change at the first sign-in.
• Role: changes the role (viewer, architect or admin).
• Reset password: sets a new password, which the user must change at the next sign-in.
• New API token: a token for Compass (Settings → Team (Compass Hub)) and for MCP clients. It is shown only once, and the previous token of the user stops working.
• Remove: removes the user. The hub always keeps at least one admin, and you cannot remove yourself.

Changing or removing a user ends their sign-ins. Every change of the users goes to the audit trail.

Configuration (hub.json)

{"listen":"127.0.0.1:8730",
 "sources":[
  {"id":"shop-db","name":"Shop (PostgreSQL)","properties":"shop-db/app.properties"},
  {"id":"shop-file","name":"Shop (file)","properties":"shop-file/app.properties"}],
 "users":[
  {"name":"anna","role":"admin","password_pbkdf2":"pbkdf2-sha256$210000$..."},
  {"name":"bob","role":"architect","token_sha256":"<SHA-256 of the token>"}],
 "integrations":{
  "jira":{"url":"https://company.atlassian.net","user":"hub@company.com","project":"ARCH","issue_type":"Task"},
  "confluence":{"url":"https://company.atlassian.net/wiki","user":"hub@company.com","space":"ARCH","parent":"65818"}},
 "policy":{"min_approval":"ask","ask_min_role":"viewer","ask_per_hour":20,
  "governance":{ ... governance.json ... }}}

• listen: the address and port; 127.0.0.1:8730 by default, 0.0.0.0:8730 in Docker. Beyond a single computer, put the hub behind HTTPS (see “Security of the hub”).
• sources: the team's models. properties is the app.properties of the given model (the same format as Compass's own settings file), relative to hub.json.
• users: you do not have to write them. Leave users out to get the default admin, and manage the users in the Users tab: the hub writes them back to hub.json with hashes only (password_pbkdf2, token_sha256). An entry with a plain "token" (at least 16 random characters) is still accepted and is turned into token_sha256 when the hub saves the users. compass-hub --hub-token (or LoonarCompass.exe --hub-token) prints a new random token and its hash. Names and tokens must be unique.
• integrations: the team's Jira and Confluence (described below); the tokens come from the secrets of the hub.
• policy: min_approval (ask, plan or auto), ask_min_role (who may use Ask in the web view; viewer by default), ask_per_hour (questions per user and hour; 20 by default) and governance in the governance.json format.

Nobody, not even an admin, approves their own change set. A change set is applied in two steps: one Compass claims it and, after the save, reports the result, so it cannot be applied twice.

Jira and Confluence from the hub

With integrations in hub.json, architects and admins get buttons in the web view. The hub works with its own service account: user (the e-mail for Cloud; empty for Data Center with a personal access token) and the tokens from the secrets JIRA_TOKEN and CONFLUENCE_TOKEN.

• Create Jira issue on an element (Search → element): an issue in the project, of the type issue_type (Task by default), with the details of the element in its description.
• Create Jira issue for this change set in a change set: one issue per change set, with its description and preview; the issue is linked in the change set.
• Publish this package to Confluence in the Model check of a package: a text page in the space (under the page parent, if given) with the elements, their descriptions and the relationships. It has no diagram pictures, because the hub has no EA. The next publication of the package replaces the page.

Every such action goes to the audit trail. The assistant in Ask stays read-only: it cannot create issues or pages.

Web view

At https://<hub>/ (http:// only on the same computer) you sign in with your user name and password. The view shows the package tree, search, element details with impact, the model check by the team rules, gaps, the audit trail, team notes and change sets, and for admins the users. In the Ask tab the assistant answers questions about the model. It only reads the model: it has no access to files, Jira, Confluence or MCP servers and cannot propose or save anything; it answers one question at a time.

Security of the hub

The hub speaks plain HTTP. For access from other computers, put it behind an HTTPS reverse proxy (for example IIS or nginx) and give people the https:// address. Change the password of the default account at once. Protect hub.json and the data folder with file permissions. Requests are limited in size and time. After 20 wrong passwords or tokens from one address, that address is refused for 10 minutes; a valid token still works. Internal errors are shown only as an id; the details are in hub.log. The web view keeps the sign-in only for the browser session and has a Sign out button.

MCP server

The MCP server (read-only) works as JSON-RPC over HTTP POST at /mcp, with the header Authorization: Bearer <token>. Tools: list_sources, list_packages, search_elements, element_details, impact_analysis, model_lint, gap_analysis.

23. Check mode for CI pipelines

With --check, Loonar Compass checks the model without the window and without the AI model, for example in a CI pipeline after every change of the model or the code. The checks are done by the program, so the same model always gives the same result, and nothing is written to the model.

LoonarCompass.exe --check --model <file.qea|app.properties>
  [--package <id|name>] [--rules governance.json] [--code <folder>]
  [--requirements <document>] [--cmdb <export.csv|json>] [--report report.md]
  [--junit junit.xml] [--fail-on error|warning|info|never] [--lang en|pl|de|fr]

What is checked

Result

• Report: Markdown on the standard output. It starts with the result, PASSED or FAILED, and the number of groups of errors and warnings, followed by a section for each part.
• JUnit: a test suite for each part and a test case for each group of findings. Groups at or above --fail-on are failures, so the pipeline shows them as failed tests.
• Exit code: 0 passed; 1 findings at or above --fail-on; 2 wrong arguments, a model that cannot be read or a file that cannot be written (the cause goes to the error output).

GitLab CI

A job on a Windows runner (PowerShell) with Loonar Compass installed for all users. The job runs the check and publishes junit.xml as the test report:

compass-check:
  tags: [windows]
  script:
    - '& "C:\Program Files\Loonar Compass\LoonarCompass.exe" --check --model model\shop.qea --rules governance.json --code src --junit junit.xml --report report.md | Out-Host'
    - 'if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }'
  artifacts:
    when: always
    paths: [report.md]
    reports:
      junit: junit.xml

GitHub Actions

A job on a self-hosted Windows runner with Loonar Compass installed for all users. The job runs the check and uploads junit.xml and the report as an artifact, which a JUnit report step of your choice can show as test results:

jobs:
  compass-check:
    runs-on: [self-hosted, windows]
    steps:
      - uses: actions/checkout@v4
      - name: Model check
        shell: pwsh
        run: |
          & "C:\Program Files\Loonar Compass\LoonarCompass.exe" --check --model model\shop.qea --rules governance.json --code src --junit junit.xml --report report.md | Out-Host
          exit $LASTEXITCODE
      - name: Publish the results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: compass-check
          path: |
            junit.xml
            report.md

For a PostgreSQL model, give --model an app.properties without passwords and set LOONAR_DB_PASSWORD: in GitLab as a masked CI/CD variable, in GitHub from a secret (env: LOONAR_DB_PASSWORD: ${{ secrets.EA_DB_PASSWORD }}).

24. License, trademarks and contact

License. Loonar Compass is freeware: you may use it free of charge on any number of computers, also for professional and commercial purposes, without time or territorial limits, and pass on unmodified copies free of charge. Modifying the application is prohibited. The license also sets out rules on AI-generated output (you review it before you approve it or rely on it), on data and on open-source components. The Polish version of the license is binding; the English, German and French versions are translations. The full text is in the About view and in the installation folder: LICENSE.txt in the installation language and, for languages other than Polish, LICENSE.pl.txt with the binding Polish version.

Privacy. The application collects no data (no telemetry). How bug reports and newsletter sign-ups are processed is described in the privacy policy; the owner's details are in the legal notice.

Open-source components. The application includes open-source libraries and fonts; each keeps its own license. The list and the license texts are in the THIRD-PARTY-NOTICES.txt file in the installation folder; in the About view, click Show licenses of the components.

Support. The application is free and will stay free. If you want to support its development, use the Support the project view or go to suppi.pl/loonar. The source code is at github.com/loonar-eu/loonar-compass.

Application owner: Loonar Mariusz Głowacki, ul. Gombrowicza 12, 73-110 Stargard.
Contact: mariusz@loonar.eu, loonar.eu. The most convenient way to report bugs is the Report a bug view.

Loonar Compass 0.8.2. Sparx Systems and Enterprise Architect are registered trademarks of Sparx Systems Pty Ltd. Claude and Anthropic are trademarks of Anthropic, PBC. OpenAI and GPT are trademarks of OpenAI. Atlassian, Confluence and Jira are trademarks of Atlassian. Microsoft, Windows, Word, Excel, Azure DevOps and GitHub are trademarks of the Microsoft group of companies. GitLab is a trademark of GitLab Inc., ServiceNow of ServiceNow, Inc., and Docker of Docker, Inc. PostgreSQL is a registered trademark of the PostgreSQL Community Association. Loonar Compass is an independent product and is not affiliated with, endorsed or sponsored by these companies.