Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lonely-lockley--archinsight/badge.svg)](/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

i

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.

  1. # Archinsight
  2. 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.
  3. 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.
  4. ## Why Archinsight
  5. - **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.
  6. - **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.
  7. - **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.
  8. - **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.
  9. - **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.
  10. - **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.
  11. - **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.
  12. ## Insight language and project model
  13. 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:
  14. - [The Insight Language](docs/language.md)
  15. - [Comments and Notes](docs/comments-and-notes.md)
  16. - [Annotations](docs/annotations.md)
  17. - [Technology icons](docs/technology-icons.md)
  18. - [Built-in Archinsight Types](docs/built-in-types.md)
  19. - [Structuring an Insight Project](docs/project-structure.md)
  20. - [Building and Linking an Insight Project](docs/project-processing.md)
  21. - [Querying the Architecture Graph](docs/graph-queries.md)
  22. The modeling guides follow the architecture from its logical context to its physical deployment:
  23. - [C1: System Context](docs/c1-system.md)
  24. - [C2: Containers and Services](docs/c2-containers.md)
  25. - [C3: Components](docs/c3-components.md)
  26. - [C4: Code](docs/c4-code.md)
  27. - [Deployment](docs/deployment.md)
  28. A small project can begin with a single `storefront.ai` file:
  29. ```insight
  30. context storefront
  31. name = Storefront
  32. external actor customer
  33. name = Customer
  34. links:
  35. -> frontend
  36. system commerce
  37. name = Commerce Platform
  38. container frontend
  39. name = Web application
  40. technology = SvelteKit, TypeScript
  41. links:
  42. -> orders
  43. service orders
  44. name = Orders API
  45. technology = Kotlin, PostgreSQL
  46. ```
  47. A separate `framework.ai` file can introduce project-specific concepts and constraints:
  48. ```insight
  49. define type PublicApi of Service
  50. constructor publicApi
  51. required Text owner
  52. required Text protocol
  53. define presentation PublicApi
  54. subtitle = protocol
  55. ```
  56. `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.
  57. 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.
  58. ## Getting started
  59. Install the CLI from npm:
  60. ```shell
  61. npm install -g @archinsight/cli
  62. archinsight --version
  63. ```
  64. Create an empty project directory and save the `storefront.ai` model shown above. From that directory, run the linker to validate the model:
  65. ```shell
  66. archinsight link .
  67. ```
  68. Then render its container view to an SVG or PNG image:
  69. ```shell
  70. archinsight render . --source storefront.ai --view c2 --format svg --out architecture.svg
  71. archinsight render . --source storefront.ai --view c2 --format png --out architecture.png
  72. ```
  73. 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.
  74. ## CLI
  75. 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.
  76. 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.
  77. Use quick actions for common semantic subdiagrams without writing a temporary
  78. `.aiq` query:
  79. ```shell
  80. archinsight quick-action isolate . --element storefront/frontend --format png --out frontend-neighborhood.png
  81. archinsight quick-action find-path . --from storefront/customer --to storefront/orders --format svg --out customer-to-orders.svg
  82. ```
  83. Find path follows relationship direction from `--from` to `--to`; swapping the
  84. arguments performs a different query.
  85. The same semantic graph operations back Isolate, Show deployment, Find path,
  86. Go to declaration, and versioned diagram Diff in the interactive diagram. In a
  87. Git-backed VS Code workspace, Diff compares two committed project snapshots,
  88. retains local blame metadata, and remains interactive. See [Diagram Quick Actions](docs/diagram-quick-actions.md)
  89. for their directed-path, environment, and neighborhood semantics.
  90. ## VSCode extension
  91. 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.
  92. 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.
  93. ## AI agent skill
  94. The CLI can place an Insight skill directly into a project:
  95. ```shell
  96. archinsight skill init . --target codex
  97. ```
  98. 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.
  99. ```shell
  100. archinsight skill init . --target claude
  101. archinsight skill init . --target generic
  102. ```
  103. Restart a Codex or Claude session after generating its native skill so the new skill is discovered.
  104. ## Web viewer
  105. 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.
  106. ## Repository
  107. The main modules are documented separately:
  108. - [CLI](archinsight-cli/README.md)
  109. - [VSCode extension](archinsight-vscode/README.md)
  110. - [Language core](packages/insight-language/README.md)
  111. - [Web viewer](archinsight-web/README.md)
  112. - [Optional renderer service](archinsight-renderer/README.md)
  113. 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.
  114. Useful development checks:
  115. ```shell
  116. npm --prefix packages/insight-language run check
  117. npm --prefix archinsight-cli run check
  118. npm --prefix archinsight-vscode run check
  119. npm --prefix archinsight-web run check
  120. npm --prefix archinsight-renderer run check
  121. ./gradlew check
  122. ```
  123. See [Testing Policy](docs/development/testing.md) for suite structure, package-specific test
  124. contracts, and the rule that coverage may not fall after a change.
  125. After editing the built-in framework, regenerate the TypeScript snapshot:
  126. ```shell
  127. npm --prefix packages/insight-language run sync:core
  128. ```
  129. Build and verify every release artifact with Gradle:
  130. ```shell
  131. ./gradlew clean dist
  132. ```
  133. This release entrypoint runs every language, CLI, VSCode, web, and renderer test
  134. suite, including coverage non-regression checks, before producing artifacts.
  135. The release includes the CLI package, VSCode extension, web distribution, and
  136. versioned `editor-ui-<version>` and `renderer-<version>` container images. Image
  137. versions come from `settings.gradle`. Override the registry/repository with
  138. `-ParchinsightImageRepository=<repository>` and the web context root with
  139. `-ParchinsightContextRoot=<path>` when required.
  140. After authenticating to the container registry, publish the web and optional
  141. renderer images with a multi-platform manifest:
  142. ```shell
  143. ./gradlew dockerPush
  144. ```
  145. The published images target `linux/amd64` by default. Local `dockerBuild` tasks
  146. still use the host architecture, so an Apple Silicon build remains runnable on
  147. the development machine. Override the publication target with
  148. `-ParchinsightDockerPlatforms=<platforms>` when required.
  149. ## License
  150. Copyright 2021-2026 Alexey Zaytsev
  151. Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.