mapture.dev

module
v0.0.0-...-83bc8a5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 14, 2026 License: MIT

README

mapture.dev

Repo-native architecture mapping that stays close to the code.

CI Canary Release Go Version License

mapture.dev is an experimental architecture graph tool for repositories that want a lightweight, reviewable source of truth for system structure. It combines mapture.yaml plus flat @arch.* and @event.* code comments, validates the result, and renders it as a polished CLI, JSON graph exports, and an interactive explorer.

Status: early preview. mapture.dev is under active development and not production-ready yet, but the validator, export pipeline, examples, and local explorer are ready for evaluation and feedback.

mapture.dev explorer on the ecommerce example

3-minute quickstart

Clone the repo and run the current examples locally:

git clone https://github.com/mandotpro/mapture.dev.git
cd mapture.dev

go run src/main.go validate examples/demo
go run src/main.go serve examples/ecommerce

Then open the local explorer and inspect the bundled example graph. For the repo’s day-to-day wrappers and testing helpers, run make help. Release packaging and distribution scripts live under scripts/release/.

For local development:

make build
make serve ecommerce

make build refreshes the embedded web bundle automatically when the frontend is stale. make serve <fixture> always rebuilds the embedded web bundle first, then rebuilds the binary, so the local explorer reflects the latest frontend and backend changes. Use make web only when you want a frontend-only rebuild.

Once installed, mapture --help and mapture --version show the current version, detected release channel, install source, and whether a newer build is available for that channel.

Install

Quick install with curl

Install the latest stable release into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/mandotpro/mapture.dev/main/scripts/install.sh | bash

Install the rolling canary channel:

curl -fsSL https://raw.githubusercontent.com/mandotpro/mapture.dev/main/scripts/install.sh | bash -s -- --channel canary

Override the install directory when needed:

curl -fsSL https://raw.githubusercontent.com/mandotpro/mapture.dev/main/scripts/install.sh | MAPTURE_INSTALL_DIR=/usr/local/bin bash

The curl installer supports macOS and Linux on amd64 and arm64. If the latest stable release does not have prebuilt archives yet, the installer will tell you and you can use Homebrew, source install, or the canary channel until the next stable cut lands.

Homebrew

Tap the dedicated Homebrew repository once:

brew tap mandotpro/mapture

Install the rolling canary channel today:

brew install mandotpro/mapture/mapture-canary

Stable mapture Homebrew packages are published from semver releases cut on the 0.x branch. Both channels install the same mapture binary, so switch channels by uninstalling the other formula first.

Prebuilt archives
Build from source
go install github.com/mandotpro/mapture.dev/cmd/mapture@latest

Install the current main branch from source:

GOPROXY=direct go install github.com/mandotpro/mapture.dev/cmd/mapture@main

For a reproducible stable source install, prefer an explicit semver tag once the current v0.x.y line is published:

go install github.com/mandotpro/mapture.dev/cmd/mapture@v0.x.y

Notes:

  • Use GOPROXY=direct with @main for source-installed canary/dev builds. Branch installs are cached aggressively by the public Go proxy, so direct fetches are more predictable for the moving main branch.
  • @latest follows the newest Go-visible module version. Until the next plain v0.x.y stable tag is published, that may still resolve to a recent main pseudo-version instead of the latest stable release.
  • Source installs use Go module version metadata. Release archives and Homebrew builds keep the channel version injected at build time.
Upgrade an existing install

mapture update upgrades the current binary in place and follows the active release channel by default.

  • Homebrew installs delegate to brew upgrade
  • Go installs delegate to go install
  • Direct binary installs download the matching GitHub release asset and replace the current executable
  • mapture --help and mapture --version will suggest Run: mapture update when a newer build is available for the detected channel

Examples:

mapture update
mapture update --channel stable
mapture update --channel canary

For troubleshooting or quick confirmation:

mapture --version
mapture version

That output includes the current version, channel, detected install source, and resolved binary path so it is easier to spot stale Homebrew canaries or older direct installs.

What mapture.dev does today

  • Validates catalog ownership, domains, events, and architecture references
  • Scans Go, PHP, TypeScript, and JavaScript comment blocks for @arch.* and @event.* tags
  • Builds a normalized graph with deterministic node and edge identities
  • Exports a shareable JSON Graph Format artifact plus explorer-facing visualisation JSON
  • Serves an interactive local explorer UI for browsing the graph
  • Ships example fixtures for demo, ecommerce, migration, and invalid validation cases

Current limitations

  • Comments-first only. No AST or Tree-sitter source analysis yet.
  • The public graph and UI are still evolving under pre-v1.0.0 versioning.
  • Mermaid export is being rebuilt on top of the JGF export model and is not part of the current CLI surface.
  • AI bundle export is planned, but not yet implemented.
  • Release channels are early: canary builds are convenient for evaluation, not stability guarantees.

Why comments-first

mapture.dev is designed for teams that want architecture metadata to live close to the code and stay reviewable in pull requests.

That means:

  • no heavy source instrumentation
  • no separate modeling tool to keep in sync
  • one small config file for ownership and domain references
  • portable annotations that work across mixed-language repos

Supported source languages

  • Go
  • PHP
  • TypeScript
  • JavaScript

Examples

Release channels

  • Stable semver releases are cut from maintenance branches such as 0.x and 1.x.
  • Merges into main do not publish immediately; one canary build is published nightly if main changed since the previous canary.
  • Stable releases are intentional: merge a PR into 0.x or 1.x with title release: patch, release: minor, or release: vX.Y.Z, or run the manual stable-release workflow.
  • Homebrew canary installs are synced to mandotpro/mapture from the canary workflow.
  • Stable release assets and the stable Homebrew formula are published after the tag is created.

Maintainer release flow

For the next stable version on a maintenance branch:

./scripts/release/plan-release.sh 0.x patch

That prints the next version and the PR title to use.

Recommended flow:

  1. Merge the intended changes into 0.x or 1.x.
  2. Merge a PR into that branch with title release: patch, release: minor, or release: vX.Y.Z.
  3. The merged PR creates the tag.
  4. The Release workflow publishes the archives and updates Homebrew.

Manual fallback:

  • Run the Stable Release workflow from GitHub Actions.
  • Provide the target branch and either a bump or an explicit version.

Contributing and support

Further reading

License

MIT

Directories

Path Synopsis
cmd
mapture command
examples
demo/src/go/ordersdb
@arch.node database orders-db @arch.name Orders Database @arch.domain orders @arch.owner team-commerce @arch.db.type tenant
 @arch.node database orders-db @arch.name Orders Database @arch.domain orders @arch.owner team-commerce @arch.db.type tenant
ecommerce/src/go/billing/billingdb
ecommerce/src/go/billing/paymentapi
ecommerce/src/go/billing/paymentservice
ecommerce/src/go/billing/stripebridge
invalid/comment-bad-event-role/src/go/broken
migration/src/go/orders/contracts
migration/src/go/orders/ordersapi
migration/src/go/orders/ordersdb
migration/src/go/orders/ordersservice
scripts
build-web command
build-web installs and builds the embedded frontend bundle under src/internal/webui/dist.
 build-web installs and builds the embedded frontend bundle under src/internal/webui/dist.
src
Mapture — repo-native architecture graph tool.
 Mapture — repo-native architecture graph tool.
cmd
Package cmd wires up the Mapture CLI.
 Package cmd wires up the Mapture CLI.
internal/bootstrap
Package bootstrap scaffolds repository config and starter catalogs for `mapture init`.
 Package bootstrap scaffolds repository config and starter catalogs for `mapture init`.
internal/catalog
Package catalog defines the canonical catalog model (teams and domains) and loads it from mapture.yaml and optional legacy YAML files.
 Package catalog defines the canonical catalog model (teams and domains) and loads it from mapture.yaml and optional legacy YAML files.
internal/config
Package config loads and validates repository-level Mapture configuration.
 Package config loads and validates repository-level Mapture configuration.
internal/exporter/html
Package html writes static explorer bundles backed by visualization JSON.
 Package html writes static explorer bundles backed by visualization JSON.
internal/exporter/jgf
Package jgf builds the shareable JSON Graph Format export for downstream consumers.
 Package jgf builds the shareable JSON Graph Format export for downstream consumers.
internal/exporter/mermaid
Package mermaid renders normalized graphs as Mermaid flowcharts.
 Package mermaid renders normalized graphs as Mermaid flowcharts.
internal/exporter/visualization
Package visualization builds the explorer-facing JSON derived from the JGF export.
 Package visualization builds the explorer-facing JSON derived from the JGF export.
internal/graph
Package graph defines the normalized architecture graph model that the scanner produces and that exporters consume.
 Package graph defines the normalized architecture graph model that the scanner produces and that exporters consume.
internal/projectscope
Package projectscope applies ad-hoc CLI scan scopes on top of discovered project config.
 Package projectscope applies ad-hoc CLI scan scopes on top of discovered project config.
internal/scanner
Package scanner walks configured source trees and extracts structured `@arch.*` and `@event.*` metadata from comment blocks.
 Package scanner walks configured source trees and extracts structured `@arch.*` and `@event.*` metadata from comment blocks.
internal/schema
Package schema embeds the CUE definitions used to validate YAML inputs.
 Package schema embeds the CUE definitions used to validate YAML inputs.
internal/server
Package server hosts the `mapture serve` local explorer.
 Package server hosts the `mapture serve` local explorer.
internal/ui
Package ui provides shared CLI reporting primitives for rich and plain-text terminal output.
 Package ui provides shared CLI reporting primitives for rich and plain-text terminal output.
internal/updater
Package updater upgrades the current mapture installation in place.
 Package updater upgrades the current mapture installation in place.
internal/validator
Package validator turns scanned raw blocks plus catalog metadata into a normalized graph and enforces validation layers 4-6.
 Package validator turns scanned raw blocks plus catalog metadata into a normalized graph and enforces validation layers 4-6.
internal/webui
Package webui exposes the embedded frontend bundle used by the server.
 Package webui exposes the embedded frontend bundle used by the server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.