Learn Navo quickly

Navo is a config-driven systems architecture browser: interactive graph, service detail, wiki reader, and a Git-first path for shared links. This path gets you from zero to exploring a map in about ten minutes.

Prerequisites: Node.js 22+ (or current LTS) and network access for package install. Optional: Go 1.23+ if you prefer the operator CLI path.

• Open the application root (the directory that contains package.json — nested navo/ in the monorepo).
• Install and start the dev server with pnpm.
• Open the local URL (typically http://localhost:5173).
• Pan and zoom the graph, click a service, open service detail, and skim the wiki.

cd navo   # directory with package.json
pnpm install
pnpm dev

predev runs compile:config so YAML maps become JSON the SPA can import. If the graph fails to load, run pnpm run validate:config for a clear diagnosis.

The SPA uses pnpm. The optional Go operator CLI lives in navo-cli/navo-cli/ and can start the same local stack.

# SPA path
cd navo
pnpm install
pnpm run compile:config
pnpm dev

# Operator CLI path (optional)
cd navo-cli/navo-cli
make build
./bin/navo doctor
./bin/navo start local

• compile:config parses architecture YAML → Zod → integrity checks → generated JSON.
• pnpm dev starts Vite; production builds use pnpm build then pnpm preview or Docker.
• navo start local auto-discovers the SPA app dir when run from the monorepo; override with --app-dir or NAVO_APP_DIR.

Authoring format is YAML. Zod in the app is the schema source of truth; JSON Schema is emitted for CI and editors. API version: dynavigen/v1 · Kind: ArchitectureMap.

apiVersion: dynavigen/v1
kind: ArchitectureMap
metadata:
  id: my-platform
  title: My Platform
  version: "0.1.0"
  updatedAt: "2026-07-14T00:00:00Z"
source:
  mode: local
groups:
  - id: core
    label: Core
nodes:
  - id: example-svc
    groupId: core
    label: Example Service
    category: runtime
    summary: "Short blurb for the summary panel."
    technicalSummary: "Longer technical narrative."
    pros:
      - Fast to operate
    fiveW:
      who: Platform team
      what: Example service
      when: Always-on
      where: Production cluster
      why: Demonstrates Navo detail fields
    links:
      - type: wiki
        label: Runbook
        href: /wiki/example.md
      - type: repo
        label: Source
        href: https://github.com/example/svc
edges:
  - id: example-uses-db
    source: example-svc
    target: example-db
    relation: uses

Node categories include orchestration, iac, runtime, data, secrets, identity, gitops, network, and more. Edge relations include uses, runs_on, orchestrates, connects_to, and others. Link types: wiki, url, repo, runbook.

Git holds the YAML. Build and CI compile it into JSON the SPA imports. Validation fails the pipeline the same way it fails locally — no soft “advisory vibes.”

pnpm run validate:config   # Zod + integrity
pnpm run compile:config    # writes src/generated/**
pnpm run schema:emit       # schemas/architecture.schema.json
pnpm build                 # prebuild compiles again

• Produces src/generated/architecture.json (primary map).
• Produces src/generated/systems/*.json plus a catalog index for multi-system switching.
• Generated JSON is gitignored — commit YAML; rebuild in CI and deploy.
• Wire validate:config + build on every PR (Azure Pipelines example ships with the app).

Home (/) is a Cytoscape compound graph with groups, category colors, neighborhood highlight, and decorative flow particles on solid edges.

• Deep link /?node=<id> selects a node on load.
• Click a node for neighborhood highlight and summary panel.
• More information opens /services/<id> for full narrative.
• In production, structural edge changes stay in-session until you download YAML and open a Git PR.

Service detail (/services/:id) is the deep narrative surface for a single node.

• Technical summary and pros list
• 5W panel: who / what / when / where / why
• Links: wiki (in-app), url, repo, runbook
• Related services derived from graph edges (in and out)
• Tags and group membership
• Personal overlay: add links, hide base links, write notes (localStorage)

Notes and personal links stay on this browser until you export. Team source of truth is always Git after a PR merges.

Ship multiple architectures in one deployment. Each map is a YAML file under config/systems/ (or the primary config/architecture.yaml).

# Scaffold with the operator CLI
./bin/navo init \
  --id my-platform \
  --title "My Platform" \
  --out ./navo/config/systems

pnpm run validate:config
pnpm run compile:config
pnpm dev
# Use the System menu on the graph toolbar to switch maps

• metadata.id must be unique, kebab-case, and stable forever.
• The System dropdown is available when two or more maps are compiled.
• Overlays are keyed by base map id/version — switching systems uses the overlay for that map.

Navo includes a static markdown reader at /wiki/:path*. Default content lives under public/wiki/. Service links with type wiki route into the app instead of bouncing to an external portal.

• Rendered with markdown-it + DOMPurify (HTML disabled for safety).
• Optional filesystem folder pick (File System Access API + webkitdirectory fallback).
• Optional portalBaseUrl fallback when a page 404s.
• ADO wiki-sync (pnpm run wiki:sync) pulls Azure DevOps Wiki into public/wiki for offline/static deploys.
• Live browser ADO Wiki API is not shipped; authoring stays in your wiki tool of choice.

links:
  - type: wiki
    label: Runbook
    href: /wiki/services/payments.md

Personal annotations live in browser localStorage. They are never team SoT until someone merges an export into Git.

Open Share (/config/share). Export overlay JSON (notes, positions, link patches) for a peer on the same base version, or export merged config (links only — notes never appear) for a Git PR.

• On version mismatch: reset, apply links only, or cancel.
• Recommended team path: export merged YAML → branch → validate:config → PR → merge → redeploy.

Structural edges are part of the ArchitectureMap (edges[]). Personal URL/wiki links on a service page are a different layer (overlay).

• Home → Edit links on the toolbar (pan/zoom freeze).
• Click source service, then target service.
• Choose a relation or remove existing edges between the pair; Save.
• In pnpm dev, Save can write edges into the active map YAML via the config API.
• In production/Docker, Save updates the session graph only — use Download YAML and open a PR.
• Lock layout snapshots positions into the personal overlay for demos.

The Go operator CLI (navo) is the windlass: chart maps, convert diagrams, start and stop local or Docker deploys. Git remains the system of record; the SPA is the theater.

cd navo-cli/navo-cli
make build                 # → bin/navo
./bin/navo version
./bin/navo doctor
./bin/navo targets
./bin/navo start local      # or: start docker --build
./bin/navo status
./bin/navo stop local

Exit codes: 0 success, 1 runtime/validation failure, 2 usage error, 3 partial success (soft warnings).

navo scan walks a directory, parses supported languages, maps modules and dependencies as edges, and writes an ArchitectureMap YAML.

./bin/navo scan ./my-project --dry-run

./bin/navo scan ./my-project \
  -o ./navo/config/systems/my-project.yaml \
  --title "My Project Architecture"

# Optional filters
./bin/navo scan ./my-project --lang go,ts --exclude "**/tests/**"

• Supported languages: Go, TypeScript/JavaScript, C#, Python.
• Flags include --id, --title, --description, --json, --max-files, --truncate.
• After generation: pnpm run validate:config, compile, and select the map in the System menu.

Use the Navo operator CLI inside a release or post-merge pipeline so architecture YAML tracks the code that just landed. Git remains the system of record: the pipeline scans (or converts), validates, commits map updates back to the repo, and GitOps (Argo CD or Flux) redeploys a locked-down Navo SPA in Kubernetes.

Recommended loop: PR merge → release pipeline → navo scan / convert → validate:config → commit YAML to main → Argo CD / Flux sync → Kubernetes Navo image rebuild or ConfigMap refresh. Humans review topology in PRs; bots keep the map honest.

1) Install the CLI in the agent (Go build or release binary). 2) Checkout the architecture repo (or monorepo path that owns config/systems). 3) Run scans/converts for each map. 4) Validate and compile. 5) Commit only when the YAML changed. 6) Let GitOps redeploy Navo.

# Example: post-merge job on the architecture / monorepo
set -euo pipefail

# Build or fetch the operator CLI
cd navo-cli/navo-cli && make build && cd ../..
NAVO=./navo-cli/navo-cli/bin/navo

# Application code stack
$NAVO scan ./apps \
  -o ./navo/config/systems/app-stack.yaml \
  --id app-stack \
  --title "Application stack" \
  --exclude "**/node_modules/**" --exclude "**/vendor/**"

# IaC / platform automation
$NAVO scan ./infra \
  -o ./navo/config/systems/iac-platform.yaml \
  --id iac-platform \
  --title "IaC platform" \
  --lang go,py,ts

# Optional: import a diagram export if present
if [ -f ./diagrams/network.drawio ]; then
  $NAVO convert drawio \
    --in ./diagrams/network.drawio \
    --out ./navo/config/systems/network.yaml \
    --id network --title "Network architecture"
fi

# Schema + integrity (fail the job on bad maps)
cd navo
pnpm install --frozen-lockfile
pnpm run validate:config
pnpm run compile:config

# Commit map updates back to the default branch (bot identity)
git config user.name "navo-bot"
git config user.email "navo-bot@example.com"
git add config/systems/*.yaml
if git diff --cached --quiet; then
  echo "No architecture YAML changes"
else
  git commit -m "chore(navo): refresh architecture maps from pipeline scan"
  git push origin HEAD:main
fi

# Azure Pipelines sketch (post-merge on main)
trigger:
  branches: { include: [main] }
pr: none

pool: { vmImage: ubuntu-latest }

steps:
  - checkout: self
    persistCredentials: true
  - task: GoTool@0
    inputs: { version: "1.23.0" }
  - script: |
      cd navo-cli/navo-cli && make build
      ./bin/navo doctor
    displayName: Build navo CLI
  - script: |
      ./navo-cli/navo-cli/bin/navo scan ./apps -o navo/config/systems/app-stack.yaml --id app-stack
      ./navo-cli/navo-cli/bin/navo scan ./infra -o navo/config/systems/iac-platform.yaml --id iac-platform
    displayName: Scan application + IaC trees
  - script: |
      cd navo && corepack enable && pnpm install --frozen-lockfile
      pnpm run validate:config
    displayName: Validate architecture YAML
  - script: |
      git config user.email navo-bot@example.com
      git config user.name navo-bot
      git add navo/config/systems
      git diff --cached --quiet || (
        git commit -m "chore(navo): pipeline map refresh" && git push
      )
    displayName: Commit YAML if changed
  # Separate CD: image build of navo SPA + Argo CD/Flux Application watches main

• Separate human PRs (feature work) from bot map-refresh commits, or open a bot PR if your policy forbids push-to-main.
• Always run validate:config (and compile:config in the Navo image build) before serving maps.
• Point Argo CD / Flux at the repo path that builds the Navo SPA or mounts config/systems into the image.
• Lock down the in-cluster Navo: private Service, NetworkPolicy, read-only root FS, non-root, no public ingress if maps are confidential.
• Use --lang / --exclude / --max-files so scans stay fast and deterministic in CI.
• Interactive pipeline map (2D/3D): /demo/pipeline
• Locked-down continuous deployment guide: /demo/continuous-deployment

GitOps agents (Argo CD, Flux) should only deploy artifacts built from Git. Navo never becomes a second CMDB — the pipeline writes YAML; reviewers and policy gates stay on the Git path.

Import existing architecture boards instead of retyping every node. Review generated narratives before merge — converters chart topology; humans still own meaning.

./bin/navo convert lucid \
  --in ~/Downloads/My-Board.json \
  --out ./navo/config/systems/my-board.yaml \
  --id my-board --title "My Board"

./bin/navo convert mermaid \
  --in ./diagram.mmd \
  --out ./navo/config/systems/diagram.yaml \
  --id diagram --title "Mermaid map"

./bin/navo convert drawio \
  --in ./architecture.drawio \
  --out ./navo/config/systems/architecture.yaml \
  --id architecture --title "Architecture"

./bin/navo convert auto --in ./board.json --out ./map.yaml --id imported

• Lucidchart needs document JSON (not PNG/PDF).
• Mermaid supports flowcharts and sequence diagrams.
• draw.io accepts .drawio XML (compressed or plain).
• Always validate:config after convert before shipping the map.

Recommended production path: multi-stage Node build + nginx:alpine serving dist/. Trust boundary for internal maps is VPN and/or private DNS — app-level SSO is not required for MVP.

# Operator CLI
export VITE_BUILD_SHA="$(git rev-parse --short HEAD)"
./bin/navo start docker --build
./bin/navo status docker
# → http://localhost:8080

# Compose from app root
docker compose up --build

# Image only
docker build --build-arg VITE_BUILD_SHA="$(git rev-parse --short HEAD)" -t navo:local .
docker run --rm -p 8080:80 navo:local

• SPA routes: try_files $uri $uri/ /index.html
• Hashed assets cached immutable; HTML no-cache
• Security headers: X-Content-Type-Options, X-Frame-Options DENY, CSP default-src 'self'

Navo is a static SPA. Any host that serves files and rewrites unknown paths to index.html works — object storage, Azure Static Web Apps, Netlify, S3+CloudFront, internal nginx, and more.

pnpm install
pnpm build
# publish dist/ to your static host

• Configure SPA fallback so /services/:id and /wiki/* load the shell.
• Run compile:config in CI before build so maps ship with the assets.
• Stamp VITE_BUILD_SHA for the About diagnostics page when useful.
• Architecture maps are often confidential — prefer private DNS/VPN over public CDN for internal systems of record.

Elasticsearch is an optional secondary index for search and collation. It never replaces Git YAML as the system of record.

• Push maps with the TypeScript es:push CLI (pnpm scripts).
• SPA read UI is gated by VITE_ENABLE_ES.
• Production browser access should go through an API gateway/BFF — direct browser → ES is demo-only.
• Config source.mode may be local | elasticsearch | http.

Annotations, overlays, and ES documents are helpers. The architecture map your team reviews lives in Git.

navo-mcp is Navo’s Model Context Protocol server — the agent hatch for living architecture maps. It serves the same ArchitectureMap YAML humans explore in the SPA, via stdio, so coding agents get structured topology instead of pasted diagrams or invented services.

Git remains the system of record. navo-mcp is not a second catalog: default mode is read-only; writes require explicit gates and still land as YAML for humans to PR.

Quick start (Go 1.25+): build navo-mcp, point NAVO_MAPS_DIR at a directory of ArchitectureMap YAML files, and open the hatch with stdio. Use MCP Inspector or your host’s MCP panel to list tools.

cd navo-mcp/navo-mcp
make build                    # → bin/navo-mcp
export NAVO_MAPS_DIR=$PWD/testdata/maps   # or navo/config/systems
export NAVO_MCP_TOOLSETS=default
export NAVO_MCP_READ_ONLY=true

./bin/navo-mcp tool-search
npx @modelcontextprotocol/inspector ./bin/navo-mcp stdio

Default toolsets are read-only. Opt-in write and ops require --allow-write, --read-only=false, and an explicit toolset list.

Resources use the navo:// scheme so hosts can pin charts. Prompts package multi-step crew workflows (onboarding tour, data-flow explanation, SME node review) and must not invent nodes or edges missing from tool results.

Moor Cursor (or any stdio host) with absolute paths. Keep NAVO_MCP_READ_ONLY=true for day-to-day agent use.

{
  "mcpServers": {
    "navo": {
      "command": "/ABS/path/to/navo-mcp/bin/navo-mcp",
      "args": ["stdio"],
      "env": {
        "NAVO_MAPS_DIR": "/ABS/path/to/navo/config/systems",
        "NAVO_MCP_TOOLSETS": "default",
        "NAVO_MCP_READ_ONLY": "true"
      }
    }
  }
}

• Supported harbors: Cursor, VS Code (MCP), Claude Desktop, Claude Code, Gemini CLI, Grok, and other stdio MCP hosts.
• Path sandbox: all chart paths resolve under NAVO_MAPS_DIR; .. escapes are rejected.
• Payload and list caps keep tool results bounded for agent context windows.
• stderr-only logging — stdout is the MCP protocol channel under stdio.
• Pair with operator CLI scan/convert for brownfield maps, then validate in CI before agents trust new topology.
• Product narrative: /features/mcp · full operator guides live in the navo-mcp repo docs.

# Trusted local windlass only — enable write + ops explicitly
navo-mcp stdio \
  --toolsets default,write,ops \
  --read-only=false \
  --allow-write \
  --maps-dir ./config/systems

Accelerate brownfield mapping by generating architecture YAML with AI assistance and importing existing diagrams (for example Lucidchart-style boards via the operator CLI convert path). Refine drafts in Git before they become team SoT.

• Draft ArchitectureMap YAML with AI, then validate with pnpm run validate:config.
• Import diagrams with navo convert (Lucidchart JSON, Mermaid, draw.io) — see Convert diagrams.
• Scan codebases with navo scan for tree-sitter-assisted maps — see Scan a codebase.
• Product narrative and FAQs: /features/ai.

AI output is a draft. Always review topology and narratives, validate schema, and merge through Git before treating the map as team truth.