docs

From install to a cross-repo map.

Install the CLI, scan each repo, share the map with your team and your coding agents. Everything below runs on your machine unless it says otherwise.

Overview

ArchSync reads your source, resolves imports and API calls across services, and produces a .archsync-schema.json describing your system — modules, routes, controllers, services, models, and the relationships between them. You review that file in pull requests, visualize it on the canvas, or serve live source over a localhost-only bridge.

ArchSync supports JavaScript/TypeScript, Python, Go, Java, Kotlin and Dart, plus Prisma, GraphQL and OpenAPI definitions.

Install

Install globally, or run with npx for zero install:

$ npm install -g archsync
# or, no install:
$ npx archsync scan

Requires Node.js 18 or newer.

Quickstart

$ archsync login         # sign in via your browser (first time only)
$ archsync init          # creates .archsync.json + .archsyncignore
$ archsync scan          # build .archsync-schema.json
$ archsync push          # push schema to your database
$ archsync diff --merged # cross-system contract check (the key one)

archsync init automatically adds .archsync.json to your .gitignore and creates an .archsyncignore file with sensible defaults. For a self-hosted instance, add --instance your-domain.com to the login command.

Commands

Run archsync <command> --help for full options.

  • archsync login / archsync logout — sign in via your browser (device authorization). Run once per machine. Add --instance your-domain.com for a self-hosted setup.
  • archsync init — guided setup: links a project, writes .archsync.json, creates .archsyncignore, and auto-adds .archsync.json to .gitignore.
  • archsync scan — scan source files and write .archsync-schema.json. Respects .archsyncignore. Add --debug to trace what's being parsed.
  • archsync push — push the local schema to your database. Use -b for branch, --dry-run to preview.
  • archsync diff — show what changed between local and remote schema for this system.
  • archsync diff --merged — cross-system contract check. Merges every connected system's latest schema and tells you what your current change breaks in other services — down to missing fields, type mismatches, and removed routes. Run this before every push. Add --audit to see all standing mismatches, not just what you changed.
  • archsync watch — watch for file changes and auto-rescan.
  • archsync serve — start the localhost-only code bridge (binds 127.0.0.1, read-only) so the canvas shows live source.

Configuration

archsync init creates .archsync.json in your project root and automatically adds it to .gitignore. Each developer runs archsync init on their own machine — it's not meant to be committed.

{
  "projectId": "acme-platform",
  "framework": "node",
  "defaultSystem": "backend",
  "supabase": {
    "url": "https://xxx.supabase.co",
    "anonKey": "your-public-anon-key"
  },
  "scan": {
    "include": ["**/*.{js,ts,jsx,tsx,dart}"],
    "exclude": ["**/node_modules/**", "**/dist/**"]
  }
}

The anonKey is the public client key (RLS is the real security layer), so it's not a secret — but .archsync.json is gitignored by default as a precaution.

Ignore patterns (.archsyncignore)

archsync init creates a .archsyncignore file in your project root with sensible defaults. It uses the same syntax as .gitignore — globs, directory trailing slashes, and # comments. Commit this file so the whole team scans the same set of files.

# .archsyncignore — what to exclude from scanning

# Generated files
src/generated/
**/*.g.dart
**/*.freezed.dart

# Vendored SDKs
lib/vendor/

# Test fixtures
**/__fixtures__/

ArchSync always skips node_modules, dist, build, and .dart_tool regardless of what's in .archsyncignore. Additional excludes in .archsync.json under scan.exclude are merged in — use those for machine-specific or CI-specific overrides.

Live code (archsync serve)

On the canvas, clicking any entity opens its code next to it. Without the bridge you see the short snippet captured at scan time. Start the bridge and you get the real file, live from your disk — one bridge can serve every repo of a product:

$ archsync serve ../backend ../mobile-app ../admin-web

The bridge binds to 127.0.0.1, is read-only, and only serves files that appear in a scanned schema. In the canvas, every line that calls something else gets a link; clicking it opens the target’s code with an arrow from that exact line.

Context index (archsync embed)

Builds short, metadata-only cards (no source code) for every entity and flow, and stores them in your Supabase so the canvas search and your coding agents can find things by meaning — “cancel an order” finds DELETE /orders/:id.

$ archsync embed --dry-run     # build the cards, send nothing
$ archsync embed               # uses VOYAGE_API_KEY if set, else full-text only

Embeddings use your own key (Voyage voyage-code-3 by default, OpenAI supported). Re-runs only embed what changed. Without a key, search still works using full-text.

MCP for coding agents

Claude Code, Cursor and Windsurf can ask ArchSync which repos a change touches before writing code. The MCP server runs inside your own Supabase:

$ archsync mcp deploy          # once per Supabase project (needs the Supabase CLI)
$ archsync mcp token --name laptop  # personal, revocable token + editor configs
$ archsync mcp rules >> CLAUDE.md   # tell the agent to ask ArchSync first

Tools your agent gets: prepare_task, explain_flow, search, get_context, check_change and list_systems. Turn access on or off per project in Settings → Agent access. Prefer local? archsync mcp serves the same tools over stdio from your repo.

Bring your own database

ArchSync is storage-agnostic. Point the CLI at your own Supabase and your architecture data never touches ArchSync servers. Credentials are read from, in order:

  • Environment variables — ARCHSYNC_SUPABASE_URL / ARCHSYNC_SUPABASE_ANON_KEY
  • The project's .archsync.json
No credentials are bundled in the package — ArchSync only ever uses the URL and key you supply at runtime.

Database migrations

Before your first push, apply ArchSync's schema to your own Supabase project. Every migration is idempotent — written with IF NOT EXISTS / CREATE OR REPLACE, so re-running is always safe. Everything is bundled into one ordered script.

Fastest path: copy the script, then in the Supabase dashboard open SQL Editor → New query, paste, and run.

Download .sqlView it first

Prefer the command line? Apply the downloaded file with psql:

$ psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 \
      -f ALL_MIGRATIONS.sql
# SUPABASE_DB_URL = Settings → Database → Connection string (URI)

Applying the script sets up:

  • Core schema & multi-tenant RLS — projects, nodes/edges, schema commits and diffs, with row-level security so each tenant sees only its own data.
  • Team roles — owner, admin, and member per project (see Team & roles below).
  • Per-system scoped push keys — hashed at rest, validated server-side, and revocable; a key is bound to one system (e.g. consumer-app, core-backend).
  • Push approval workflow — pushes from member keys land as pending; owner/admin keys auto-approve. The live schema is always the latest approved commit.
  • Email invites, multiple named systems per team, and ownership transfer.
Upgrading ArchSync? Re-download and re-run ALL_MIGRATIONS.sql — idempotency means only the new changes apply, so it's always safe to run the latest. This page always serves the current version.
ArchSync checks your setup before connecting. When you link a database, the app runs a preflight check and refuses to proceed if any part of the schema is missing — so a half-pasted script fails fast with the exact missing pieces listed, instead of breaking mid-use. Billing and licensing are hosted by ArchSync and are not part of this script — there is nothing for you to install for them.

Team & roles

The migrations above enable team collaboration on a project. Roles are scoped per project:

  • Owner — full control; the only role that manages billing and can transfer ownership.
  • Admin — manage members and keys, and approve or reject pending pushes.
  • Member — scoped to one or more systems; can push (landing as pending for review) and sees only the keys for systems they're granted.

A team can have multiple apps, web portals, and backends — each a named system (e.g. consumer-app + driver-app, admin-web, payments-backend + core-backend). The push key is the source of truth for which system a push targets, so a contractor holding the driver-app key can only ever push to driver-app. Owners and admins create keys and review pushes directly on the canvas.

Multi-repo setup

ArchSync's cross-system detection works when every repo pushes to the same project ID. Here's the exact flow for a backend developer and a frontend developer:

Step 1 — Developer A sets up the project (backend):

$ archsync login
$ archsync init   # "Team / shared" → name it e.g. "payments-backend"
$ archsync scan && archsync push

Step 2 — Developer B links their repo to the same project (frontend / mobile):

$ archsync login
$ archsync init   # "Team / shared" → "Enter existing project ID" → paste Developer A's ID
$ archsync scan && archsync push

Both systems now appear in the same canvas. Either developer can run the cross-system check from their repo:

$ archsync diff --merged   # what does my current change break in the other system?
Neither developer needs to pull the other's schema manually. Each runs archsync scan && archsync push after making changes. diff --merged always reads the latest pushed schema for every system from the shared database.

Onboarding a team

One person — the admin — sets the team up; everyone else just accepts an invite. Nobody copies database keys. Permissions are always enforced by the database (RLS + role checks), never by a client token.

Admin — once:

  • Sign in at archsync.dev. On ArchSync Cloud, that’s it. For your own Supabase, run the setup SQL there (the Copy SQL button above) and connect it in Settings → Connected Databases.
  • Own Supabase only: in your Supabase dashboard → Authentication → URL Configuration, add https://archsync.dev/** to Redirect URLs so invite emails can bring people back to ArchSync.
  • Own Supabase, optional: Supabase’s built-in email sends only a few messages an hour. For real teams, add any SMTP provider in Authentication → Emails → SMTP Settings. To word the invite email your way, edit Authentication → Emails → Templates → Confirm signup (new people) and Magic Link (people who already have an account). {{ .Data.invited_by }} and {{ .Data.project_name }} are filled in for new accounts; always keep {{ .ConfirmationURL }} as the link.
  • Invite people from Settings → Team & Systems. They get an email; you also get a link you can share yourself.

Teammate — join:

  • Open the invite email (or link). It connects your browser to the team’s database — you see which one and confirm — signs you in and adds you to the project.
  • Install the CLI and log in. The browser you joined with approves it, and the CLI is connected to your team’s database automatically:
$ npm install -g archsync
$ archsync login       # opens archsync.dev to approve this device
$ archsync init        # lists only the projects you can access
$ archsync scan && archsync push

How the CLI finds your team’s database: archsync login starts on archsync.dev with a one-time secret in the approval link. The browser you approve in is connected to your team’s database, so it signs the CLI in there and passes back that database’s address, sealed with the secret — archsync.dev only ever relays ciphertext. Each login appears under Settings → CLI Devices, where you can revoke it. Running your own copy of the website? Use archsync login --instance your-domain.

CI & pull requests

Add ArchSync to CI to block PRs that break cross-system contracts. diff --merged exits non-zero when breaking changes are detected.

# GitHub Actions example
- name: ArchSync cross-system check
  env:
    ARCHSYNC_SUPABASE_URL: ${{ secrets.ARCHSYNC_SUPABASE_URL }}
    ARCHSYNC_SUPABASE_ANON_KEY: ${{ secrets.ARCHSYNC_SUPABASE_ANON_KEY }}
  run: |
    npm install -g archsync
    archsync scan
    archsync diff --merged   # fails if this change breaks another system

For a machine-readable diff (to post as a PR comment or parse in scripts):

$ archsync diff --json   # added/removed/modified, single-system
$ archsync diff --merged --json   # cross-system contract violations

Billing & credits

ArchSync has three ways to use it:

  • Free — one person on their own repos: scan, diff, validate, explain, serve, watch and the canvas on local files. No account, never metered.
  • Solo — adds archsync mcp for your own AI agent. One person.
  • Team — adds everything shared: archsync push to your own Supabase, the team canvas, hosted MCP for every teammate, members and roles.

Solo and Team are paid with prepaid credits, not a subscription. You buy a pack once; credits never expire, and paid actions draw them down. Nothing renews and there is nothing to cancel.

Credits belong to an organisation, not a seat, and are capped by a rolling 5-hour window (below). Your architecture data still lives entirely in your own database — ArchSync billing only stores your account email, organisation, credit balance and a usage log.

The 5-hour usage window

Credits are capped by a rolling 5-hour window, not drained all at once. Your tier sets how many credits you can spend in any 5-hour span; spend freely under that ceiling, and the window rolls forward continuously. This keeps day-to-day work feeling unlimited while smoothing big bursts.

Hitting the window ceiling never spends anything — you wait for it to roll off, raise your tier for a bigger window, or buy a one-time boost. Your purchased credits are untouched and never expire.

Tiers (higher = more throughput per 5 hours):

  • Free — a small window to get started.
  • Pro — a larger window for active teams.
  • Max — the largest window for heavy, continuous use.

Raising your tier is a one-time unlock, not a subscription. The live meter in Settings → Billing always shows how much of your current window is used and when it resets.

What costs credits

Each metered action draws a fixed number of credits. The server is the source of truth for these costs.

ActionCreditsWhat it is
archsync push2Sync a system’s schema to your team database
Cross-repo merge3Combine schemas from multiple repos into one canvas
Breaking-change scan2Cross-stack impact / blast-radius analysis
AI insight4AI architecture recommendation (LLM inference)
Canvas session1A day of active shared-canvas use, per user
MCP session2An agent connecting to ArchSync MCP (each start of archsync mcp, or each hosted session)
Export1PDF or image export of a map

These are the current defaults — costs are set per action and can change. When the balance runs out, paid actions stop with a clear message until an owner or admin tops up; everything in Free keeps working.

Buying credits

  1. Open the canvas → Settings → Billing and sign in to your ArchSync account (or create one). Teams on their own database sign in here separately — this account only holds billing.
  2. Create an organisation and choose Solo or Team. You become its owner and get the organisation key once.
  3. Choose a pack and pay. Payments are processed by Razorpay. Only the owner or an admin can buy.
  4. On Team, invite people by email. They join when they sign in with that email, and each creates their own key.

In India you pay in rupees (INR) — UPI, Indian cards, net banking and wallets. Outside India you pay in US dollars with PayPal: choose USD next to “Buy credits” (it is preselected outside India) and the checkout opens PayPal. International cards outside PayPal are not accepted yet.

  • Solo — 300 credits (Solo organisations)
  • Starter — 200 credits
  • Growth — 1,000 credits
  • Scale — 3,000 credits

Credits land on your org’s balance as soon as the payment is confirmed. The Billing tab shows your current balance, a breakdown of what you’ve spent, and your recent activity. See pricing for current pack prices.

Billing runs on ArchSync’s hosted service — there is nothing to install for it, even on the Team (bring-your-own-database) plan. Self-hosted Enterprise instances include the billing schema in their deployment.

Activate credits for the CLI

archsync push needs a Team key and archsync mcp needs a Solo or Team key. Each person creates a personal key in Settings → Billing → Use it from the CLI and agents and activates it once per machine. Usage is recorded against that person, and removing someone from the organisation revokes their keys.

$ archsync license activate ask_lic_xxxxxxxx   # store & verify your key
$ archsync license status                       # plan + remaining credits
$ archsync license logout                       # remove the key from this machine

The key is stored in ~/.archsync/license.json at mode 0600 — the same posture as ~/.npmrc or the AWS CLI. In CI, set it as the ARCHSYNC_LICENSE_KEY secret instead. Once activated, each push uses 2 credits (a cross-repo diff --merged uses 3, an agent session 2) and prints your remaining balance. Paid actions are confirmed with ArchSync before they run, so they need a connection to archsync.dev; everything in Free keeps working offline.

For hosted agent access, an owner or admin runs archsync mcp deploy on a machine where the organisation key is active; it is stored as the function’s secret in your own Supabase. The organisation key can be rotated from Settings → Billing.

Privacy & security

  • Scanning is fully local — nothing is uploaded by scan.
  • archsync serve binds strictly to 127.0.0.1, is read-only, and only serves files present in the scanned schema.
  • archsync push is the only command that sends data anywhere, and only to the database you configure.

Found a gap in the docs? Open an issue.