Skip to content

Getting Started with ArcaMira

Looking for the full documentation? This is the role-based quick start. For the complete documentation set — product reference, how the tool supports the EA function, and detailed help guides — see the documentation home.

This guide covers three entry points depending on your role:

What is this tool?

A living architecture repository for mid-market IT organizations. It lets your architecture team document what the organization has (applications, technologies, data, capabilities, initiatives), how those things connect, and what risks or changes are coming. Stakeholders get read-only views and summaries without needing to understand the underlying model.

The core idea: start with what you have, not what you should have. You don't need a complete capability map or a perfectly structured metamodel before you get value. Import a spreadsheet of applications, add a few relationships, and the tool starts showing you something meaningful within an hour.

Admin / First Deployer

Step 1 — Stand up the stack

Docker (fastest): 

docker compose up
# UI at http://localhost:5173  |  API at http://localhost:3001
# Default login: admin@demo.local / password

Manual dev: 

cd api && npm install && npm run dev   # port 3000
cd ui  && npm install && npm run dev   # port 5173, needs ui/.env.local

ui/.env.local minimum: 

VITE_DEV_TENANT=demo
VITE_API_URL=http://localhost:3000

The API auto-runs pending database migrations on startup — nothing to run manually for fresh installs.

Step 2 — Create your first users

Go to Admin → Users. Create accounts and assign roles:

Role What they can do
viewer Read-only; sees stakeholder summary pages
editor Create and edit entities, add relationships, comment
admin Everything above plus user management, settings, approval workflow

Viewers are automatically redirected to a clean stakeholder summary page when they visit any entity — they never see the editing UI.

Step 3 — Configure the tenant

Admin → Settings controls:

  • Approval workflow — set which roles can approve entities for the review workflow
  • Integrations — connect ServiceNow, Azure, AWS, or Microsoft Entra ID for automated asset discovery (see Asset Discovery below)

Step 4 — Get data in

The fastest path is Import / Export (under Add & Connect in the left nav). The tool accepts:

  • Domain scan — the lowest-friction start: type your domain and ArcaMira reads its public DNS (SPF, MX, DMARC, domain-verification records) to spot the SaaS you're visibly using — no login, no agent, results in seconds. Confirm the ones that are real into the Discovery Queue. It's a head start, not a complete inventory (it sees SaaS that touch your mail/DNS); connect Microsoft Entra ID for SSO + shadow-IT coverage.
  • CSV import — applications, capabilities, technologies, etc. Column headers map to entity fields. Start with your CMDB or application list.
  • ArchiMate XML — if you're migrating from another EA tool, export to ArchiMate 3.x and import directly.

After import, entities appear in the appropriate landscape view. You can then enrich them incrementally — add descriptions, link relationships, assign criticality tiers — at whatever pace suits the team.

Asset Discovery

If you have ServiceNow, Azure, or AWS connected under Admin → Settings → Integrations, discovered assets land in the Discovery Queue rather than being added automatically. This gives your team a triage step: accept (create the entity), or dismiss (it's a known non-entity). Accepted items are pre-tagged with their discovery source.

SaaS discovery from your identity provider (Microsoft Entra ID). Most of a mid-market estate is SaaS, and your IdP already knows about it. The Entra ID integration reads your estate from Microsoft Graph across two signals and shows a preview first: Microsoft first-party and system apps are filtered out, apps you've already catalogued are recognised (including fuzzy name matches — "SFCC" meets "Salesforce Commerce Cloud"), and nothing is written until you confirm. Confirmed apps land in the Discovery Queue tagged SaaS.

The signals:

  • SSO (enterprise applications) — every app wired into single sign-on. Sanctioned IT.
  • OAuth consent grants — apps a user or admin clicked "allow" on (Calendly, Notion, Grammarly and the like). This catches the third-party SaaS that never became a full SSO app — often shadow IT. Apps found only by an individual user's consent are badged shadow IT in the preview.
  • Usage — for each app, last sign-in and how many distinct people have signed in (within the log-retention window). A one-user, months-dormant app is an obvious dismiss/decommission candidate; a broadly-used one clearly stays. Shown per row and saved on the entity.
  • Dependencies — OAuth consent grants also record which apps call which other apps' APIs. Where both ends are apps in your estate, ArcaMira lays these down as "integrates with" relationships — so the discovered apps arrive already wired into the dependency graph that impact analysis and blast radius run on, not as isolated entries. (Microsoft-first-party resources like Graph are treated as noise and skipped; the value is app↔app integrations.)

Not the same as Entra sign-on. Entra single sign-on (how users log in) is configured separately under Settings → General → Single Sign-On. This discovery integration uses the same Entra tenant but only reads your app inventory — it does not affect login. The two use different permissions (sign-on uses delegated OpenID Connect scopes; discovery uses the application permissions below), so you can either add these read permissions to your existing sign-on app registration or create a dedicated one.

Setup (one-time, needs an Entra admin): 1. In the Entra admin center, create an app registration (or reuse your sign-on one) and note the Directory (tenant) ID and Application (client) ID; create a client secret. 2. Under API permissions → Add a permission → Microsoft Graph → Application permissions, add Application.Read.All (SSO discovery), Directory.Read.All (OAuth/shadow-IT signal), and AuditLog.Read.All (usage signal) — then click Grant admin consent. (Sign-in/OIDC delegated scopes are not enough; the connection test reports precisely if consent is missing. Each signal degrades independently — with only Application.Read.All you still get SSO discovery, and the preview tells you which signals are off and how to switch them on.) 3. In ArcaMira: Admin → Settings → Integrations → Microsoft Entra ID, paste the three values, Test the connection, then Discover.

This is a read-only app inventory — ArcaMira does not read license counts, spend, or user-level sign-in data.

EA Practitioner

Mental model: Entities and Relationships

Everything in the repository is an entity. Entities belong to a layer and have a type:

Layer Common types
Business Capability, Process, Org Unit, Principle
Application Application, Portfolio
Technology Technology component
Data Data entity, Data store, Data pipeline, Data product
Governance Standard, Decision (ADR), Initiative

Entities are connected by relationships (e.g. an Application supports a Capability, a Technology hosts an Application). The relationship types are configurable under Admin → Relationship Types, but sensible defaults are pre-loaded.

Where to start

1. Map your capability model first (/capabilities)

The capability map is the organizing spine of the repository. L1 domains → L2 capabilities → L3 sub-capabilities. Even a rough 2-level map (10–20 capabilities) gives you something to hang applications against. Use Capability Discovery (in the Discover section) for AI-assisted suggestions based on your org's industry and context.

2. Catalog your applications (Estate → Assets, Applications lens)

The Assets surface — one unified inventory with a lens switcher for Applications, Technology, and Data — is where most orgs spend the most time. For each application, you want at minimum: - Which capabilities it supports - Its criticality tier (T1 Mission Critical / T2 Business Critical / T3 Standard) - Its lifecycle status (Active / Planned / Retiring) - The technology stack it runs on

The application entity page has an inline-editable profile sidebar — click any field to edit it without entering an "edit mode."

3. Add your technology components (Estate → Technology)

The Technology page groups technology by vendor and lifecycle stage, with Risk and Radar tabs. Flag anything in End of Life — the Risk tab surfaces blast radius (how many applications depend on that component).

4. Build a View (/views)

Views are curated diagrams — subsets of entities and relationships on a canvas. Create one per domain or initiative. Use the auto-layout button to arrange nodes; drag to reposition; use Shift+click or box-select for multi-select. Views have a status workflow (Draft → Review → Approved) for governance.

Entity pages — how they work

Each entity type has a purpose-built page that leads with what matters for that type:

  • Application — criticality picker, profile sidebar (owner, lifecycle, hosting), NFR targets (availability, RTO, RPO)
  • Capability — hierarchy position, what delivers it (applications, processes)
  • Technology — lifecycle banner (warning if End of Life), blast radius (what depends on it)
  • Initiative — scope (what it delivers, retires, enables), owner, dates, budget
  • Data Entity — data classification (sensitivity, regulatory flags, PII), lineage, storage

All fields are inline editable — click any field to edit it. No edit mode, no Save button (auto-saves on blur or Enter). The "Edit all fields" link at the bottom is a fallback for fields not surfaced inline.

Discover & Connect

The Discover workspace (/discover) shows you relationship gaps — entities that exist but aren't connected to anything, or capabilities with no supporting applications — alongside AI-suggested capability links to confirm. Use it periodically to find blind spots in the model. (The Discovery Queue at /discovery is separate — it's for triaging assets that arrive via AWS / Azure / ServiceNow sync, Microsoft Entra ID SaaS discovery, and domain DNS scan.)

AI-assisted capability suggestions: in Discover, and inline on any entity page, ArcaMira suggests capability linkages based on the entity's name and description. Click to confirm; it creates the relationship.

Review workflow

Entities can be put through a review cycle: Draft → Under Review → Approved → Archived. The Decisions & Reviews hub (/governance/decisions-reviews) shows the review queue alongside ADRs, the standing Review Board, tracked conditions, and the denials register. The ARB workflow supports two methods — a solution review (govern a change) and a selection scorecard (weighted vendor/candidate comparison). Approvers are set in Admin → Approval Workflow. Use this for significant new entities or material changes — you don't need to review everything.

Governance artifacts

Governance lives in two hubs: Standards & Principles (/governance/standards-principles — principles, standards, the policy-exception register, and compliance posture) and Decisions & Reviews (/governance/decisions-reviews — ADRs and the ARB review workflow). Link standards to entities to show what applies to which applications or technologies.

Import and export

Import / Export supports both directions — export a full tenant backup or a filtered set of entities to CSV for offline analysis. ArchiMate XML export is available for interoperability with other tools.

Business Stakeholder / Viewer

You have read-only access. Here's what's most useful:

Stakeholder summary pages

When you visit any entity (application, capability, etc.), you'll see a clean stakeholder summary: a single-scroll card with the entity's description, key relationships, risk signals (if any), and which architecture views include it. No editing controls, no clutter.

If you want to see the full network of what connects to a given application or capability, click "Open in diagram" from the summary page to see it on the canvas.

Key views to bookmark

View What you'll find
/capabilities The capability map — what the organization does, hierarchically
/assets The Assets surface — filterable inventory of applications, technology, and data
/roadmap Initiatives timeline — what's changing, when
/views Architecture diagrams — curated views by domain or project
/reports Health summary — coverage gaps, lifecycle status, tech risk headlines

Following entities

On any entity page, click Follow (bell icon in the top-right) to get notified when that entity changes. Useful if you need to stay current on a specific application or initiative.

Stakeholder view vs. full view

If an EA team member shares a link to an entity and you see editing controls, it's because your account has an editor or admin role. Viewers only ever see the stakeholder summary. Ask your admin if you need a role change.

Common first-session checklist

For most orgs, a useful first session looks like this:

  • [ ] Import application list from CMDB or spreadsheet
  • [ ] Create a rough capability map (L1 + L2 is enough to start)
  • [ ] Link 5–10 applications to the capabilities they support
  • [ ] Set criticality tiers on your top 20 applications
  • [ ] Create one architecture view for a key domain
  • [ ] Invite one business stakeholder as a viewer and show them the stakeholder summary page

That's enough to demonstrate value and get meaningful feedback on what to fill in next.

Where to get help

  • Ask Your Architecture (header AI icon, or /ai-query) — natural language query against your own repository data. "Which applications support the Claims Processing capability?" returns results from your actual entities, not generic answers. Requires an AI provider to be configured.
  • In-tool comments — every entity has a comments thread. Use it for questions or context that should live with the asset.
  • For issues or feature requests: open an issue in the project repository.