archinsight
Simplicity in Code, Power in Design
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/lonely-lockley/archinsight with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/lonely-lockley/archinsight'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/lonely-lockley--archinsight)HTML
<a href="/listings/lonely-lockley--archinsight"><img src="/api/listings/lonely-lockley--archinsight/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install the CLI from npm:
npm install -g @archinsight/cli archinsight --version
Create an empty project directory and save the `storefront.ai` model shown above. From that directory, run the linker to validate the model:
archinsight link .
Then render its container view to an SVG image:
archinsight render . --source storefront.ai --view c2 --format svg --out architecture.svg
The resulting `architecture.svg` contains the systems, containers, services, and relationships selected by the built-in C2 query. You can now split the model across files, introduce definitions, or open the directory in the VSCode extension without changing its semantic identities.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 223 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # Archinsight
- Archinsight is a toolkit for software architecture modelling as code. Models are written in the typed, extensible Insight language and linked into a semantic project graph used for validation, navigation, dependency analysis, queries, deployment projection, and diagram generation.
- The project includes a CLI, a VSCode extension, a generated skill for AI agents, and a web viewer. The CLI, extension, and web viewer use the same language runtime, so types, diagnostics, queries, linking, and rendering behave consistently across interactive and automated workflows. Agent skills teach AI tools how to work with an Insight project and validate their changes through the same CLI and linker.
- ## Why Archinsight
- - **Model with a type system.** Types describe required attributes, references, valid nesting, relationships, deployment mappings, and other structural rules. The linker checks those rules across the project, while editors and agents use the same schema for completion and navigation.
- - **Capture the vocabulary of an organization.** Teams can define their own types, constructors, operators, infrastructure capabilities, enums, and visual conventions. Reviewed framework definitions become reusable architectural building blocks instead of loose tags or naming conventions.
- - **Keep architecture facts separate from their representations.** The linked semantic graph is the authoritative model. C1, C2, C3, C4, Deployment, source-focused, and custom views are derived from that graph rather than maintained as independent diagrams.
- - **Trace logical dependencies through deployment.** Profiles map logical elements to concrete deployments, while projections expand logical dependencies into the network and infrastructure paths that implement them. Different environments can realize the same logical relationship in different ways without duplicating the logical model.
- - **Make ownership and provenance explicit.** Contexts establish logical boundaries, source files remain explicit units of authorship, and imports record dependencies between source boundaries. `extend` allows several sources to contribute to one model object without losing where each contribution came from.
- - **Scale the model independently from the repository layout.** Semantic identities come from contexts, environments, and model objects rather than file paths. Models can be reorganized, split, and extended without renaming the architecture they describe.
- - **Derive views for the question at hand.** Graph queries can select architectural levels, source scopes, relationships, inherited types, derived dependencies, deployment projections, and visual groups. Built-in C1, C2, C3, C4, Deployment, and unfiltered views are ordinary queries over the same linked model.
- ## Insight language and project model
- Insight is the language used to define both architecture models and the frameworks that describe their vocabulary. The language documentation covers its type system, built-in architecture types, project structure, linker semantics, and graph query model:
- - [The Insight Language](docs/language.md)
- - [Comments and Notes](docs/comments-and-notes.md)
- - [Annotations](docs/annotations.md)
- - [Technology icons](docs/technology-icons.md)
- - [Built-in Archinsight Types](docs/built-in-types.md)
- - [Structuring an Insight Project](docs/project-structure.md)
- - [Building and Linking an Insight Project](docs/project-processing.md)
- - [Querying the Architecture Graph](docs/graph-queries.md)
- The modeling guides follow the architecture from its logical context to its physical deployment:
- - [C1: System Context](docs/c1-system.md)
- - [C2: Containers and Services](docs/c2-containers.md)
- - [C3: Components](docs/c3-components.md)
- - [C4: Code](docs/c4-code.md)
- - [Deployment](docs/deployment.md)
- A small project can begin with a single `storefront.ai` file:
- ```insight
- context storefront
- name = Storefront
- external actor customer
- name = Customer
- links:
- -> frontend
- system commerce
- name = Commerce Platform
- container frontend
- name = Web application
- technology = SvelteKit, TypeScript
- links:
- -> orders
- service orders
- name = Orders API
- technology = Kotlin, PostgreSQL
- ```
- A separate `framework.ai` file can introduce project-specific concepts and constraints:
- ```insight
- define type PublicApi of Service
- constructor publicApi
- required Text owner
- required Text protocol
- define presentation PublicApi
- subtitle = protocol
- ```
- `PublicApi` inherits the service schema, adds two required attributes, and receives its own constructor and presentation. The linker requires `owner` and `protocol` on every `publicApi` declaration, while language tooling can discover the same schema for completion and navigation.
- Insight keeps framework definitions separate from architecture models. A definitions file contains `define` and `extend type` declarations, while context declarations such as the `storefront` model live in their own files. Mixing definitions and a `context` in the same source file produces an error.
- ## Getting started
- Install the CLI from npm:
- ```shell
- npm install -g @archinsight/cli
- archinsight --version
- ```
- Create an empty project directory and save the `storefront.ai` model shown above. From that directory, run the linker to validate the model:
- ```shell
- archinsight link .
- ```
- Then render its container view to an SVG or PNG image:
- ```shell
- archinsight render . --source storefront.ai --view c2 --format svg --out architecture.svg
- archinsight render . --source storefront.ai --view c2 --format png --out architecture.png
- ```
- The resulting `architecture.svg` contains the systems, containers, services, and relationships selected by the built-in C2 query. You can now split the model across files, introduce definitions, or open the directory in the VSCode extension without changing its semantic identities.
- ## CLI
- The CLI is the local and automation interface for an Insight project. It links and validates models, prints project structure, executes graph queries, renders diagrams, produces semantic visual diffs between git revisions, runs deterministic diagram quick actions, and generates agent skills.
- The [CLI reference](archinsight-cli/README.md) describes the query, render, diff, quick-action, and output options. Every diagram-producing command supports `text`, `json`, `dot`, `svg`, and `png`. Diagram rendering follows the system light/dark preference by default and accepts an explicit `--theme light` or `--theme dark` override.
- Use quick actions for common semantic subdiagrams without writing a temporary
- `.aiq` query:
- ```shell
- archinsight quick-action isolate . --element storefront/frontend --format png --out frontend-neighborhood.png
- archinsight quick-action find-path . --from storefront/customer --to storefront/orders --format svg --out customer-to-orders.svg
- ```
- Find path follows relationship direction from `--from` to `--to`; swapping the
- arguments performs a different query.
- The same semantic graph operations back Isolate, Show deployment, Find path,
- Go to declaration, and versioned diagram Diff in the interactive diagram. In a
- Git-backed VS Code workspace, Diff compares two committed project snapshots,
- retains local blame metadata, and remains interactive. See [Diagram Quick Actions](docs/diagram-quick-actions.md)
- for their directed-path, environment, and neighborhood semantics.
- ## VSCode extension
- The [Archinsight VSCode extension](https://marketplace.visualstudio.com/items?itemName=archinsight.archinsight-vscode) provides diagnostics, completion, semantic highlighting, project structure, source navigation, and a source/result split editor for `.ai` and `.aiq` files. It supports built-in views, custom graph queries, typed table reports, diagram export, and JSON/CSV table downloads.
- Open a workspace containing `.ai` files and then open a model. The extension embeds the language runtime for interactive editing and diagram preview, and follows the active VS Code theme without reloading the editor. The CLI adds command-line validation and CI integration using the same project semantics.
- ## AI agent skill
- The CLI can place an Insight skill directly into a project:
- ```shell
- archinsight skill init . --target codex
- ```
- Targets are available for `codex`, `claude`, and `generic`. The generated skill contains the modeling workflow, language references, built-in framework sources, query recipes, quick-action subdiagram workflows, and examples. It instructs the agent to inspect the existing project, use deterministic quick actions where they fit, and validate changes through the CLI rather than approximating the language independently.
- ```shell
- archinsight skill init . --target claude
- archinsight skill init . --target generic
- ```
- Restart a Codex or Claude session after generating its native skill so the new skill is discovered.
- ## Web viewer
- The SvelteKit web viewer presents linked projects in a browser using the same language core and editor components. It supports project-owned `.aiq` custom views, including filename-based overrides of built-in queries. It provides an authenticated owner-scoped application and an anonymous read-only playground containing one explicitly published project.
- ## Repository
- The main modules are documented separately:
- - [CLI](archinsight-cli/README.md)
- - [VSCode extension](archinsight-vscode/README.md)
- - [Language core](packages/insight-language/README.md)
- - [Web viewer](archinsight-web/README.md)
- - [Optional renderer service](archinsight-renderer/README.md)
- The language core lives in `packages/insight-language`. Built-in Insight framework sources are stored under `src/main/resources/com/github/lonelylockley/insight`. The CLI, extension, and web viewer consume a generated snapshot of those sources.
- Useful development checks:
- ```shell
- npm --prefix packages/insight-language run check
- npm --prefix archinsight-cli run check
- npm --prefix archinsight-vscode run check
- npm --prefix archinsight-web run check
- npm --prefix archinsight-renderer run check
- ./gradlew check
- ```
- See [Testing Policy](docs/development/testing.md) for suite structure, package-specific test
- contracts, and the rule that coverage may not fall after a change.
- After editing the built-in framework, regenerate the TypeScript snapshot:
- ```shell
- npm --prefix packages/insight-language run sync:core
- ```
- Build and verify every release artifact with Gradle:
- ```shell
- ./gradlew clean dist
- ```
- This release entrypoint runs every language, CLI, VSCode, web, and renderer test
- suite, including coverage non-regression checks, before producing artifacts.
- The release includes the CLI package, VSCode extension, web distribution, and
- versioned `editor-ui-<version>` and `renderer-<version>` container images. Image
- versions come from `settings.gradle`. Override the registry/repository with
- `-ParchinsightImageRepository=<repository>` and the web context root with
- `-ParchinsightContextRoot=<path>` when required.
- After authenticating to the container registry, publish the web and optional
- renderer images with a multi-platform manifest:
- ```shell
- ./gradlew dockerPush
- ```
- The published images target `linux/amd64` by default. Local `dockerBuild` tasks
- still use the host architecture, so an Apple Silicon build remains runnable on
- the development machine. Override the publication target with
- `-ParchinsightDockerPlatforms=<platforms>` when required.
- ## License
- Copyright 2021-2026 Alexey Zaytsev
- Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.