Architecture DocumentationArcShape architecture This directory documents ArcShape in Markdown using the twelve sections of arc42. Product intent is owned by docs/product/model/; this documentation describes implementation and distinguishes current behavior from planned capabilities. Sections Introduction and goals Architecture constraints System scope and context Solution strategy Building block view Runtime view Deployment view Cross-cutting concepts Architecture decisions Quality requirements Risks and technical debt Glossary Markdown is the source of truth. Implementation claims link to repository evidence. Inferred intent is not treated as an accepted decision.
Introduction and goalsRequirements overview ArcShape is a local toolkit for turning a repository into a readable, reviewable architecture workspace. Its npm package provides a deterministic CLI; its optional capability package gives selected agent providers portable instructions for investigating and maintaining the documentation. Capability What the maintainer gets Onboard A twelve-section arc42 scaffold, with optional provider capabilities. Investigate Resumable evidence sessions that record coverage, changes, findings, and open questions. Maintain Validation, ADR and C4 authoring workflows, and explicit sync to selected destinations. Read and share A self-contained reader generated from the canonical Markdown. Quality goals Priority Goal Architectural response 1 Preserve authored documentation Initialization never overwrites files whose contents differ from package templates. 2 Keep architecture claims evidence-grounded The session CLI records evidence coverage and drift; assistant workflows interpret evidence and leave changes reviewable. 3 Work across repositories The package does not select repositories by programming language; coverage follows available evidence. 4 Make documentation readable Markdown remains canonical and the reader site is generated from it. The CLI owns setup, validation, bookkeeping, and rendering. Skills guide investigation and authoring; they do not accept documentation changes on the maintainer's behalf. Stakeholders Stakeholder Need Repository maintainer Install the tool and retain control of documentation changes. Agent providers Discover and run selected ArcShape skills using repository context. Architecture reader Understand the system through a navigable, self-contained view.
Architecture constraintsTechnical constraints The package targets Node.js 22 or newer and uses npm packaging. Architecture documentation, ADRs, and diagram sources use Markdown as their canonical form. Agent workflows use portable Agent Skills with provider adapters. Codex, Cursor, Windsurf/Cascade, Gemini CLI, OpenCode, and GitHub Copilot share .agents/skills/; Claude Code uses .claude/skills/. Provider compatibility follows each provider's documented discovery paths; ArcShape does not claim runtime testing inside provider applications. Organizational constraints Repository maintainers review proposed architecture documentation before accepting it. ArcShape does not operate a hosted service to inspect or store adopter repositories. External publication or synchronization must be directed and reviewed by the maintainer. Conventions Keep canonical architecture sources portable Markdown in docs/architecture/. Keep the twelve arc42 sections in their standard order. Mark uncertainty and separate observed implementation from product intent.
System scope and contextBusiness context The maintainer owns the repository and decides which documentation changes to accept. ArcShape runs locally in that repository: it creates the Markdown workspace, records evidence-session state, validates the documents, and renders the reader. A selected agent provider may use installed skills to inspect evidence and draft changes, but the provider is an external host rather than an ArcShape service. Readers consume the Markdown directly or use the generated static site. Optional sync commands publish to destinations chosen by the maintainer. ArcShape packages canonical skills separately from the CLI and installs them into the provider-specific discovery paths. The CLI detects local evidence, lets the maintainer select providers, previews file operations, and tracks managed-file hashes. It does not launch agents or contact marketplaces. Obsidian synchronization is local; Confluence publication is directed and explicit. In both cases, external writes are bounded by a selected destination and conflict detection. Technical context Open full screen ↗The boundary is intentionally small: ArcShape is the local CLI, while the repository and publication destinations remain outside it. Agent providers are deliberately absent from this context view because they consume installed Markdown skills inside the adopter repository rather than calling an ArcShape service; that interaction is shown in the container view. arcshape init creates scaffold files and selected skill instructions; it does not contact an ArcShape service or launch an agent. External publication is never implicit in initialization.
Solution strategyTechnology decisions ArcShape is distributed as the @arcshape/cli npm workspace package and runs locally in the adopting repository. Canonical documentation lives in docs/; the repository root is a private npm workspace that owns development tooling. The CLI and architecture reader are implemented in packages/cli/src/, and distributable templates and capabilities are in packages/cli/assets/. Top-level decomposition packages/cli/src/bin/arcshape.mjs dispatches human-invoked CLI commands. packages/cli/src/bin/ contains CLI modules for setup, capability management, sessions, validation, and documentation sync. packages/cli/src/arc42-site/ contains the architecture reader implementation. packages/cli/assets/architecture/ contains the Markdown scaffold shipped in the package. packages/cli/assets/capabilities/ contains provider-neutral skills, the provider discovery registry, and exact legacy hashes for migration. src/public-site/ contains the ArcShape-owned static product site source and assets. Cloudflare Pages serves this surface independently of engineering-artifact publication. src/engineering-portal/ contains the compact landing page published at the GitHub Pages root. The workflow generates the Product Snapshot and Architecture Snapshot from canonical Markdown into separate routes. docs/product/model/ records product intent; it is not generated from implementation. openspec/ contains temporary delivery planning and validation integration. Quality realization The CLI uses exclusive file creation and compares existing content before deciding whether a file is up to date or conflicts. AI reasoning is reserved for the separate assistant workflow layer; deterministic CLI commands own setup and bookkeeping.
Building block viewLevel 1: system ArcShape is a private npm workspace whose distributable CLI runs inside an adopter's repository. It combines deterministic repository operations with an optional package of provider-neutral skills and a Markdown reader. The workspace root owns development dependencies and repository automation. ArcShape has no server or database. Level 2: building blocks Building block Responsibility Evidence CLI entry point Parses commands and routes setup, evidence sessions, validation, sync, and site builds. packages/cli/src/bin/arcshape.mjs CLI modules Implement repository setup, capability management, sessions, validation, and documentation sync. packages/cli/src/bin/ Architecture templates Supplies the README and twelve arc42 Markdown sections. packages/cli/assets/architecture/ Capability package Supplies provider-neutral skills, provider discovery metadata, and managed-file hashes. packages/cli/assets/capabilities/ Site renderer Validates Markdown, renders Mermaid and native sources, and publishes either a single-file snapshot or an interactive directory. packages/cli/src/arc42-site/ Native diagram adapter Validates bounded JSON, invokes the pinned renderer, exports static SVG and isolates the browser viewer. native-diagrams.mjs, native-viewer.mjs Product and publication surfaces Remain adjacent repository artifacts: product intent, public site, engineering portal, and delivery workflows. docs/product/model/, src/, .github/workflows/ C4 container view The CLI installs canonical Markdown and optional agent skills into the selected repository. Agent providers remain external hosts; ArcShape does not host an AI runtime. Local state records evidence sessions, sync baselines, and capability ownership. The diagram separates those responsibilities so the write paths are visible without implying that an agent provider calls an ArcShape server. Open full screen ↗
Runtime viewRuntime scenarios Initialize a repository Safe ArcShape initialization flowRenderer: MermaidSource Markdown: docs/architecture/06-runtime-view/README.mdSource revision: 39cc95b100f5b00463eb54832e2390622d2c0e1eSafe ArcShape initialization flowMermaid diagram rendered from docs/architecture/06-runtime-view/README.md.Target repositoryInstalled packageArcShape CLIMaintainerTarget repositoryInstalled packageArcShape CLIMaintaineralt[File is absent][Contents match][Edited or symlinked]loop[Each planned file action]Request initLoad scaffold and selected skillsShow scope, actions, and conflictsConfirm planRecheck path and contentCreate exclusivelyKeep unchangedPreserve and report conflictReport created, unchanged, and preserved filesInitialization is preview-first and deliberately boring: it does not inspect source code, make architecture claims, contact an ArcShape service, or launch an agent. It installs the README, twelve arc42 sections, and optionally selected arc- skills. The CLI rechecks each destination before writing, creates absent files exclusively, and preserves edited or symlinked paths as conflicts. Agent lifecycle commands use the same planning and ownership-manifest approach. Validate architecture Markdown arcshape validate loads the architecture README and twelve numbered sections. New adopters use one NN-slug/README.md directory per section and may add supporting Markdown there; the legacy flat layout remains compatible during migration. The command checks the arc42 frontmatter contract and can print a human-readable summary or machine-readable JSON. Site generation runs the same structural validation before writing HTML. Synchronize with an Obsidian vault arcshape sync obsidian --vault <path> copies Markdown files from the architecture directory to a selected vault folder. Repeatable --include options add selected Markdown directories such as docs/architecture/09-architecture-decisions; ArcShape preserves a shared relative directory structure so links between the selected documents continue to work. A local manifest records content hashes. On later runs, ArcShape updates a note only when its current content still matches the last synced version; local edits are reported as conflicts. Source files removed from the repository are reported as orphaned vault notes and are not deleted. arcshape sync confluence --base-url <url> --space-id <id> --parent-id <id> reads the selected parent page and publishes an index plus one child page per arc42 section. Repeatable --include options add selected Markdown files or directories such as ADRs. --dry-run reports create, update, unchanged, and conflict actions without writing. A local manifest tracks each managed page and protects remote edits from being overwritten. The single-page --page-id mode remains available. Credentials are read from configured environment variable names and are not stored in the repository. Build the reader site arcshape site build reads the README, twelve canonical section documents, and any supporting Markdown beneath their section directories, validates their frontmatter and filenames, converts Markdown to sanitized HTML, pre-renders accessible Mermaid diagrams, and writes the requested output file (default docs/architecture-site/index.html). Supporting Markdown keeps its authored relative paths in the reader: nested folders become collapsible navigation groups, folder README.md files provide folder pages, and supporting pages show contextual breadcrumbs. The GitHub Pages workflow writes its projection to _site/architecture/index.html with the exact source revision. It does not modify canonical Markdown. Native fences add one build-time rendering step. The default snapshot embeds their static images; --format interactive publishes compact viewers and dedicated pages from the same source. Validation or rendering errors stop publication. An interactive directory is replaced only when its ownership inventory still matches every file. The existing initialization sequence above remains Mermaid because its loops and alternatives carry meaning. Open full screen ↗The diagram shows the successful path. Malformed input, a rendering failure, or modified output leaves the prior publication in place. The runtime boundary is explained in cross-cutting concepts; the trade-off is recorded in ADR-0002. Resume an evidence-analysis session arcshape session start inventories safe regular files and assigns stable evidence IDs. session next returns one bounded round at a time, starting with documentation, then repository configuration, then implementation and tests. status, next, and report refresh file hashes to identify additions, modifications, and removals. A mark operation records a classification and an optional note; changed evidence requires re-reading and explicit acceptance before it can be classified. Leads and questions are stored as supplied by the human or AI workflow. Run risk-based CI assurance The dedicated assurance workflow runs a Playwright Chromium journey against a temporary initialized repository and generated reader. A separate job builds the reader from the checked-out commit, serves it only on the ephemeral runner, and runs OWASP ZAP Baseline in passive mode. The severity adapter reports all findings and fails for High risk. The weekly and manually dispatched mutation job runs Stryker's Vitest runner against the bounded onboarding and provider-lifecycle modules and retains its report. New assurance check contexts are not required by the main ruleset pending maintainer review of measured thresholds and findings.
Deployment viewInfrastructure overview ArcShape runs as a local Node.js process in the adopter's repository. The source repository publishes the @arcshape/cli package through a reviewed, environment-gated release workflow; release mechanics and recovery belong in docs/releasing.md, not in this topology view. Session state is stored locally in .arcshape/sessions/<session-id>/session.json. It is not sent to an ArcShape service. Obsidian sync writes Markdown into the selected local vault and stores its manifest beside those notes. Confluence sync stores page mappings and content hashes in .arcshape/confluence-sync/; multi-page mode publishes an index and the twelve arc42 sections plus any explicitly selected Markdown beneath the chosen Confluence Cloud parent page only when run without --dry-run. Deployment mapping Environment What lives there Boundary ArcShape source repository CLI source, templates, canonical product and architecture Markdown Maintained by the project; CI reads it and produces projections. GitHub Actions Engineering portal build, release verification, and assurance jobs Ephemeral execution; the protected publish environment gates npm publication. GitHub Pages Engineering portal and source-revision-stamped snapshots Public static artifact generated from the source repository. Cloudflare Pages Public product site static output Separate product-site publication path. npm registry Versioned @arcshape/cli package Distribution only; it does not store adopter documentation. Adopter repository Local CLI process, canonical architecture Markdown, and .arcshape/ state The primary runtime boundary. Selected destination Obsidian notes or Confluence pages Written only by an explicit sync command; conflicts stop overwrites. Published artifacts and adopter deployment The source repository produces three independent kinds of output: the public product site, the engineering portal, and the npm package. Adopters install the package into their own repository, run the CLI locally, and choose whether to publish the generated reader. ArcShape does not operate the adopter's runtime, reader host, Obsidian vault, or Confluence space. The companion Archify publication-boundaries diagram is a standalone static artifact generated from the reviewed candidate at .archify/arcshape-publications/arcshape-publication-boundaries.json. ArcShape publication and adopter deployment boundariesRenderer: MermaidSource Markdown: docs/architecture/07-deployment-view/README.mdSource revision: 39cc95b100f5b00463eb54832e2390622d2c0e1eArcShape publication and adopter deployment boundariesMermaid diagram rendered from docs/architecture/07-deployment-view/README.md.Adopter-controlled repositoryPublished artifactsGitHub ActionsArcShape source repositoryProject governanceauthors and reviewsmaintainsreleasesinstallinit, validate, syncsite buildoptional publicationMaintainerCanonicalarchitectureMarkdownPublic productsite sourceCLI packagesourceBuild portalVerify releaseProtectedpublish gateGitHub PagesportalCloudflarePages sitenpm registryLocalArcShape CLIArchitectureMarkdownSelf-containedreaderOptional hostor docsdestination
Cross-cutting conceptsOwnership and authority Product intent, implementation behavior, quality constraints, and architecture records have separate owners. The ProductShape model states what ArcShape should do; architecture Markdown explains how this repository realizes it. Generated readers and published snapshots are projections, not alternate sources of truth. Security and privacy Repository setup, validation, site generation, session state, and Obsidian sync operate locally. Confluence sync sends the selected architecture Markdown to the explicitly configured space and parent page when run without --dry-run; credentials are read from environment variables and are not persisted. Initialization refuses to overwrite differing authored files and refuses to write through symlinked paths. Assistant skills are local Markdown instructions; external AI providers have their own data handling policies. Diagram execution and publication Native diagram JSON stays in canonical Markdown. The adapter validates the pinned family schema and rejects resource-bearing inputs before rendering. The package contains a minimal Archify subset with file hashes and attribution; the build browser blocks network requests and exports a sanitized static SVG. This is trusted local build execution, not a sandbox for third-party renderer plugins. Interactive pages execute the viewer in sandbox="allow-scripts" iframes, without same-origin access. Dedicated pages keep the same boundary by assigning inert viewer data to a sandboxed srcdoc frame. Both wrappers validate message source windows and bounded message shapes; they accept no arbitrary URLs or DOM commands. CSP restricts scripts to generated hashes and blocks network connections. Static images remain available without JavaScript. Publication stages the entire directory before replacing intact ArcShape-owned output. Its file-hash manifest detects modified or unrelated files; output cannot overlap the authored documentation or traverse symlinks. Snapshot generation retains the existing single-file contract. See ADR-0002 and the fictional family gallery. Observability and operations The CLI reports created, unchanged, updated, orphaned, and conflicting files or pages for sync. Initialization is repeatable and has no persistent service state. Analysis sessions, sync baselines, and capability ownership are stored locally under .arcshape/. Native diagram family galleryThese examples describe the fictional Brisa reservation system, not ArcShape services. They demonstrate renderer coverage, not universal Mermaid compatibility. Canonical ArcShape diagrams remain in their owning sections. architecture Open full screen ↗class Open full screen ↗dataflow Open full screen ↗erd Open full screen ↗lifecycle Open full screen ↗sequence Open full screen ↗timeline Open full screen ↗tree Open full screen ↗waterfall Open full screen ↗workflow Open full screen ↗
Architecture decisionsThis directory is the canonical Architecture Decision Record collection for ArcShape. The section README is both the arc42 section document and the navigation index for every ADR. Keep records directly here by default, or group them in stable project-defined subdirectories. ADR index Keep this table sorted alphabetically by ADR title. Include every record, regardless of status, and link to its stable relative path. ADR Status Date Isolate native diagram viewers and retain static snapshots (ADR-0002) Proposed 2026-10-27 ADR-0001 Accepted 2026-10-21 Do not create a parallel docs/adr/ collection or duplicate ADR bodies in this section document. ADR-0001: Keep ADRs in architecture section 09Context ArcShape's canonical architecture documentation is organized as twelve numbered section directories. A separate docs/adr/ collection would split architecture navigation between two roots and require two overlapping ADR workflows. ArcShape has no downstream adopters yet, so the repository can establish the canonical layout before the first public adoption. Decision Keep every ArcShape Architecture Decision Record under docs/architecture/09-architecture-decisions/. The section README.md is the arc42 section document and the alphabetical index for every ADR. Records use the existing ADR-NNNN-kebab-case-title.md convention by default and may be grouped in stable subdirectories when a project needs it. Do not create a parallel docs/adr/ collection. Alternatives considered Keep docs/adr/ as a separate collection: rejected because it duplicates the architecture navigation boundary and keeps two ADR workflows in the repository. Put ADR bodies directly in the section README: rejected because individual records need stable links, independent history, and optional project grouping. Use a new ADR metadata or resolver format: rejected because the existing Markdown and frontmatter contract is sufficient. Consequences Positive: Section 09 is the single discoverable entry point for architecture decisions, and the generated reader can render each ADR as supporting material with a stable route. Positive: ArcShape's packaged arc-adr skill and its .agents and .claude dogfood copies share one unambiguous workflow. Negative: Repositories with an existing flat ADR collection need a one-time migration into section 09 or an explicit established-convention exception. Neutral: The ArcShape CLI continues to read legacy flat arc42 section files during migration; the canonical new layout remains directory-based. References ArcShape architecture navigation ArcShape ADR skill Issue #84 ADR-0002: Isolate native diagram viewers and retain static snapshotsContext The maintainer approved bringing the compact interactive prototype into ArcShape while preserving Mermaid and single-file documentation. The prototype depended on a separate Archify checkout and same-origin access to its viewer. Shipping those assumptions would couple consumers to a development machine and give diagram code access to the reader. Decision Propose storing typed native JSON in Markdown fences and bundling a pinned Archify renderer subset. Build both representations from that source: static SVG for the default snapshot, and an explicit directory with embedded and dedicated interactive viewers. Preserve existing Mermaid without automatic conversion. Run viewer scripts only inside opaque-origin iframes, including on dedicated pages. Exchange bounded selection, theme and scrolling messages with the trusted wrapper. Publish no directly navigable raw runtime artifact. Retain visible static output if scripting is disabled or startup fails. Include vendor integrity and MIT attribution without embedded font or third-party brand payloads. Alternatives considered Keep the PoC's external checkout and same-origin iframe: not portable and does not enforce the parent-document boundary. Load a CDN renderer: incompatible with reproducible offline publication. Replace Mermaid entirely: loses unsupported diagram semantics and breaks existing documents. Reimplement every layout: discards the tested renderer and expands the maintenance scope. Consequences One authored source supports static reading and exploration. Interactive publication remains an explicit choice. Upstream runtime APIs and DOM structure are versioned integration dependencies. Updates require export, browser-isolation and visual regression tests. The package grows by the renderer subset; its inventory is included in SBOM assurance. Renderer execution is trusted build-time code with validated data, fixed paths, a minimal environment and execution limits. It is not an operating-system sandbox. Node filesystem permissions conflict with upstream ancestor-path inspection; this implementation does not claim confinement it cannot enforce. Native migration remains opt-in. External documentation targets must keep a readable representation or retain Mermaid. References Issue #109 Reader runtime Viewer isolation Native adapter Pinned vendor inventory
Quality requirementsQuality tree Safety: protect user-authored files and avoid unintended external data transfer. Portability: use Markdown sources that remain readable outside ArcShape. Usability: make setup and conflicts understandable to maintainers. Traceability: connect product-intent statements to ProductShape and implementation claims to repository evidence. Quality scenarios Scenario Expected response Run initialization twice without changes The second run reports all scaffold files as unchanged and makes no content changes. A maintainer already authored one target file ArcShape reports a conflict, preserves the file, and continues with other absent files. The architecture path contains a symlink ArcShape reports the conflict and does not write through it. CI assurance scenarios Scenario Expected response Run the onboarding and reader E2E journey A temporary repository is initialized, authored architecture content is generated, and the browser can reach and read the updated section through a local preview. Add a synthetic High-risk alert to the ZAP report fixture The severity-policy self-test proves that High fails while Medium remains report-only. Run the scheduled/manual mutation baseline Stryker records killed, survived, timed-out, and uncovered mutants for the selected high-risk modules and retains the JSON/HTML reports. Consider making assurance a required merge check A maintainer reviews observed thresholds, severity, runtime, and flakiness before any ruleset update. Run in a directory without Git metadata Initialization still creates the Markdown workspace.
Risks and technical debtRisks Risk Impact Response A consumer assumes init generated architecture facts The empty scaffold could be mistaken for analyzed documentation Keep setup and AI analysis as separate commands; state that the scaffold is structure only. Repository evidence varies by language and quality Analysis depth varies across repositories Report coverage and uncertainty without an allowlist or equal-depth promise. Documentation sync overwrites authored content Loss of user data Obsidian and Confluence sync track prior hashes and stop when target content changed. Assistant providers handle data under their own policies Maintainer expectations may be wrong Explain provider responsibility before enabling AI workflows. The public reader site can lag canonical Markdown after a failed deployment Readers may see an older architecture snapshot Monitor the Pages workflow and rerun it from main after fixing the failure. Browser, mutation, or passive DAST signals may be slow or noisy Maintainers may lose confidence or spend excess CI time Keep jobs isolated and bounded, retain reports, document reruns, and keep the new contexts outside required branch protection until evidence and policy are reviewed. Technical debt The pinned native viewer depends on upstream DOM and export APIs. Its browser tests and vendor hashes must pass before an update; system-font metrics still require visual inspection. ADR-0002 records the proposed trade-off. The native renderer is trusted package code, not an OS-isolated plugin. Source validation excludes filesystem/network-bearing features, while browser isolation protects readers. The residual build-time dependency risk remains part of security review. The CLI records evidence and validates arc42 structure; assistant workflows still depend on the selected AI provider to interpret evidence. ADRs and C4 diagrams are Markdown authoring workflows; the static site and external sync currently publish the arc42 architecture directory. The Mermaid renderer adds browser and diagram dependencies that need continued dependency review before public release. Release publication depends on external npm and GitHub environment configuration; the versioned workflow and recovery instructions are committed, but those external settings are not architecture-owned state.
Glossary Term Definition Architecture documentation Markdown description of a system's structure, behavior, constraints, and quality attributes. arc42 A twelve-section template for communicating software architecture. Analysis session Local state that tracks repository evidence, review coverage, findings, leads, questions, and resume progress. Canonical Markdown Repository-authored documentation from which validation and reader outputs are derived. Capability A provider-neutral, packaged set of instructions and references for one ArcShape workflow. ProductShape The product-definition-as-code model that states what ArcShape is intended to do. Reader site Self-contained static web output generated from canonical architecture Markdown. Sync baseline Local content hashes used to detect whether a destination changed before ArcShape updates it.
