Archwise is a local-first, open-source workspace for discovering, understanding, explaining, and safely experimenting with software architecture.
Project status (
main, pre-release): local Alpha preview. Node package-manifest discovery, an evidence-backed package dependency graph, a protected loopback API, a Svelte 5/Svelte Flow Architecture Studio, an autosaved Sandbox with resumable sessions and versioned JSON import/export, and deterministic offline coaching questions are implemented. A deterministic hypothetical Sandbox capacity simulation is now available with visible assumptions; production-traffic observation, deep infrastructure discovery, multi-revision history, and AI interviewing remain future work. Discovered graphs are recorded as versionedarchwise.graphv1 revisions, and Sandbox sessions autosave to a local SQLite store outside the project, so you can resume them from the Studio,--resumeor--sessions. No package or npm CLI has been published. See the roadmap status for what is delivered, what is partial, and what comes next.
Use Node 26 and pnpm 10.34.9. Run pnpm install --frozen-lockfile --ignore-scripts, then pnpm check. See the development guide for package tests and current verification limits.
After building, run node apps/cli/dist/bin.js --serve --path /absolute/path/to/project to start the protected local Studio, or use --graph to inspect the discovered package graph as JSON. See the Alpha testing guide, sandbox persistence guide and simulation model for step-by-step instructions and current limitations. Standalone pnpm dev does not provide the authenticated local graph API.
The product starts from code already on a developer's machine. From a selected working directory, Archwise discovers one or more repositories, builds an evidence-backed architecture graph, opens it in a browser, and lets the user explore a separate sandbox without changing source code. An optional AI interviewer acts like a system-design recruiter: it asks focused questions, challenges assumptions, and turns answers into reviewable suggestions.
- Local-first: source code and derived architecture data remain on the user's machine by default.
- Open-source core: discovery, graphing, browser exploration, sandboxing, and deterministic simulation are usable without an account or paid service.
- Evidence over guesses: every inferred node and edge carries provenance, confidence, and diagnostics.
- Real graph stays immutable: experiments happen in a separate sandbox layer and never masquerade as discovered facts.
- AI is optional: the product works without a model provider; users explicitly configure local or remote providers.
- Safe by default: static inspection is read-only, secrets are redacted, and project code is never executed implicitly.
- Run Archwise from a project directory or explicitly pass one or more paths.
- Review detected repositories, packages, services, data stores, APIs, queues, and infrastructure.
- Open the browser workspace with the discovered system design already loaded.
- Inspect evidence and confidence for each architectural claim.
- Fork the real graph into a sandbox, propose changes, and compare scenarios.
- Use deterministic simulations and the optional interviewer/coach to expose trade-offs.
- Export a portable architecture snapshot without modifying the repositories.
- Product specification
- Architecture and local data flow
- Automatic discovery and multi-repository workspaces
- Real graph, sandbox, and provenance model
- Sessions and the local store
- Simulation model
- AI interviewer and coach
- Security and privacy
- MVP scope and delivery phases
- End-to-end implementation roadmap
- Code organization: current and target
- CI/CD and release strategy
- Optional open-core business strategies
- Architecture decision
- Browser workspace decision: Svelte Flow
- Local store decision: node:sqlite
- Alpha testing guide
- Original README preserved as history
Start with the contribution guide for the current workflow and verification instructions. Participation is governed by the Code of Conduct.
The specification is the current source of truth. Before implementing a feature, read AGENTS.md, identify the relevant document, and propose an ADR when changing an invariant or major boundary. Keep local-only workflows functional and do not make a cloud account a prerequisite for core features.
Licensed under Apache-2.0. Contributions use the DCO process. The repository is public. No release has been published yet.