# swark-io/swark architecture

> Architecture diagram of the GitHub repository swark-io/swark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swark-io/swark
- Repository: https://github.com/swark-io/swark

## Overview

1. **Project type and boundary**
   - This is a **VS Code extension** named Swark. Its core boundary is the editor: it runs inside VS Code, reads files from the active workspace, calls the VS Code Language Model API via GitHub Copilot, and writes a Markdown/Mermaid diagram back into the workspace for preview.

2. **Entry point and command wiring**
   - `src/extension.ts` is the extension activation entrypoint.
   - It registers the main command implemented in `src/commands/create-architecture.ts`, which is the orchestration layer for the whole flow.
   - The README’s default keybinding and command palette flow both route into this command.

3. **User input and workspace selection**
   - `src/io/input-selection.ts` handles selecting the target folder or workspace scope.
   - This is the first user-facing decision point and defines the repository slice that will be analyzed.

4. **Repository ingestion**
   - `src/io/repository-reader.ts` is responsible for finding and loading source files from the selected folder.
   - It is constrained by extension filters and exclusion patterns described in the README settings, so the input to the LLM is a curated subset of the repo rather than the whole workspace.

5. **Token budgeting and file selection**
   - `src/io/language-counter.ts` and `src/llm/token-count-utils.ts` support estimating how much content can fit into the model context.
   - The extension dynamically adjusts how many files it reads based on the configured `swark.maxFiles` and the model’s token limits, so file selection is bounded by both user config and LLM capacity.

6. **Prompt construction**
   - `src/llm/prompt-builder.ts` transforms the selected code files into a structured prompt.
   - This is the main handoff from repository data into model input: it bundles code context plus instructions for producing an architecture diagram in Mermaid syntax.

7. **LLM interaction**
   - `src/llm/model-interactor.ts` performs the actual request to the VS Code Language Model API / GitHub Copilot.
   - `src/llm/debug-utils.ts` likely supports logging or inspection of prompt/response behavior for troubleshooting.
   - The architecture depends on Copilot as the only external AI provider; no separate API keys or third-party model service are used.

8. **Diagram post-processing and Mermaid-specific handling**
   - `src/view/mermaid/serde.ts`, `link-generator.ts`, and `cycle-detector.ts` form a Mermaid-focused normalization layer.
   - `cycle-detector.ts` is especially important because the README exposes a `swark.fixMermaidCycles` setting; this suggests the extension can patch or avoid Mermaid graph cycles that would otherwise break rendering.
   - This layer is the boundary between raw LLM output and renderable diagram content.

9. **Output generation and persistence**
   - `src/view/output-formatter.ts` assembles the final Markdown content, including the Mermaid block and any log/details needed for inspection.
   - `src/view/output-writer.ts` writes the artifacts into the workspace’s `swark-output` folder as two files per run: the diagram Markdown and a log Markdown file.
   - This is the main persistence boundary of the system.

10. **Preview/UI layer**
    - `src/view/viewer.ts` opens or presents the generated Markdown so the user can immediately inspect the diagram inside VS Code.
    - The extension therefore has a “generate then preview” UX, rather than exporting only to a raw file.

11. **Telemetry and observability**
    - `src/telemetry.ts` collects usage, model, timing, and error events.
    - Per the README, telemetry is privacy-preserving: it excludes source code and file contents, and is sent to Azure Application Insights via VS Code telemetry tooling.

12. **Quality and verification**
    - There are focused tests under `src/view/tests` and `src/view/mermaid/tests`, indicating the most logic-heavy areas are output formatting and Mermaid graph handling.
    - The repo also includes GitHub Actions in `.github/workflows/build.yml`, showing the extension is built and validated in CI rather than relying only on local development.

13. **Overall data flow**
    - The end-to-end architecture is: user selects scope → repository files are discovered and filtered → token budget determines how much code to include → prompt is built → Copilot/LLM generates Mermaid architecture → Mermaid is optionally repaired/normalized → Markdown diagram and log files are written → the diagram is opened in VS Code preview.

14. **Key architectural constraint**
    - The main design constraint is **LLM context size**: nearly every subsystem before model invocation exists to maximize useful code inclusion while staying within token limits, and every subsystem after invocation exists to make the generated Mermaid reliably renderable and reviewable.

Main entry points: [`src/io/repository-reader.ts`](https://github.com/swark-io/swark/blob/main/src/io/repository-reader.ts) (Repo reader), [`src/commands/create-architecture.ts`](https://github.com/swark-io/swark/blob/main/src/commands/create-architecture.ts) (Create arch), [`src/llm/model-interactor.ts`](https://github.com/swark-io/swark/blob/main/src/llm/model-interactor.ts) (Model interactor), [`src/io/input-selection.ts`](https://github.com/swark-io/swark/blob/main/src/io/input-selection.ts) (Scope picker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_extension["VS Code shell"]
  node_n_extension["Extension<br/>activation<br/>[extension.ts]"]
  node_n_command["Create arch<br/>orchestrator"]
end

subgraph group_group_input["Repository intake"]
  node_n_input["Scope picker<br/>selection<br/>[input-selection.ts]"]
  node_n_reader["Repo reader<br/>ingestion"]
  node_n_lang["Language count<br/>budgeting"]
  node_n_tokens["Token utils<br/>budgeting"]
end

subgraph group_group_llm["LLM pipeline"]
  node_n_prompt["Prompt builder<br/>prompting<br/>[prompt-builder.ts]"]
  node_n_model["Model interactor<br/>copilot-api"]
  node_n_debug["Debug utils<br/>diagnostics<br/>[debug-utils.ts]"]
end

subgraph group_group_view["Diagram output"]
  node_n_serde["Mermaid serde<br/>normalization<br/>[serde.ts]"]
  node_n_links["Link generator<br/>normalization<br/>[link-generator.ts]"]
  node_n_cycles["Cycle detector<br/>repair<br/>[cycle-detector.ts]"]
  node_n_formatter["Output formatter<br/>markdown"]
  node_n_writer["Output writer<br/>persistence<br/>[output-writer.ts]"]
  node_n_viewer["Viewer<br/>preview<br/>[viewer.ts]"]
end

subgraph group_group_obs["Observability"]
  node_n_telemetry["Telemetry<br/>events<br/>[telemetry.ts]"]
end

node_n_extension -->|"registers"| node_n_command
node_n_command -->|"select scope"| node_n_input
node_n_input -->|"scope"| node_n_reader
node_n_reader -->|"measure"| node_n_lang
node_n_lang -->|"budget"| node_n_tokens
node_n_tokens -->|"limit files"| node_n_reader
node_n_reader -->|"files"| node_n_prompt
node_n_prompt -->|"prompt"| node_n_model
node_n_debug -.->|"inspect"| node_n_model
node_n_model -->|"diagram"| node_n_serde
node_n_serde -->|"linkify"| node_n_links
node_n_links -->|"validate"| node_n_cycles
node_n_cycles -->|"repair"| node_n_formatter
node_n_formatter -->|"persist"| node_n_writer
node_n_writer -->|"preview"| node_n_viewer
node_n_command -.->|"emit events"| node_n_telemetry

click node_n_extension "https://github.com/swark-io/swark/blob/main/src/extension.ts"
click node_n_command "https://github.com/swark-io/swark/blob/main/src/commands/create-architecture.ts"
click node_n_input "https://github.com/swark-io/swark/blob/main/src/io/input-selection.ts"
click node_n_reader "https://github.com/swark-io/swark/blob/main/src/io/repository-reader.ts"
click node_n_lang "https://github.com/swark-io/swark/blob/main/src/io/language-counter.ts"
click node_n_tokens "https://github.com/swark-io/swark/blob/main/src/llm/token-count-utils.ts"
click node_n_prompt "https://github.com/swark-io/swark/blob/main/src/llm/prompt-builder.ts"
click node_n_model "https://github.com/swark-io/swark/blob/main/src/llm/model-interactor.ts"
click node_n_debug "https://github.com/swark-io/swark/blob/main/src/llm/debug-utils.ts"
click node_n_serde "https://github.com/swark-io/swark/blob/main/src/view/mermaid/serde.ts"
click node_n_links "https://github.com/swark-io/swark/blob/main/src/view/mermaid/link-generator.ts"
click node_n_cycles "https://github.com/swark-io/swark/blob/main/src/view/mermaid/cycle-detector.ts"
click node_n_formatter "https://github.com/swark-io/swark/blob/main/src/view/output-formatter.ts"
click node_n_writer "https://github.com/swark-io/swark/blob/main/src/view/output-writer.ts"
click node_n_viewer "https://github.com/swark-io/swark/blob/main/src/view/viewer.ts"
click node_n_telemetry "https://github.com/swark-io/swark/blob/main/src/telemetry.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_extension,node_n_command toneBlue
class node_n_input,node_n_reader,node_n_lang,node_n_tokens toneAmber
class node_n_prompt,node_n_model,node_n_debug toneMint
class node_n_serde,node_n_links,node_n_cycles,node_n_formatter,node_n_writer,node_n_viewer toneRose
class node_n_telemetry toneIndigo
```

## Components

### VS Code shell

Activation and command entrypoints inside the editor

- [Extension](https://github.com/swark-io/swark/blob/main/src/extension.ts): activation · VS Code extension activation entrypoint · `src/extension.ts`
- [Create arch](https://github.com/swark-io/swark/blob/main/src/commands/create-architecture.ts): orchestrator · Main command that coordinates the full generation flow · `src/commands/create-architecture.ts`

### Repository intake

Scope selection and workspace file loading

- [Scope picker](https://github.com/swark-io/swark/blob/main/src/io/input-selection.ts): selection · Chooses the target folder or workspace slice · `src/io/input-selection.ts`
- [Repo reader](https://github.com/swark-io/swark/blob/main/src/io/repository-reader.ts): ingestion · Discovers and loads source files from the selected scope · `src/io/repository-reader.ts`
- [Language count](https://github.com/swark-io/swark/blob/main/src/io/language-counter.ts): budgeting · Estimates language size for model budgeting · `src/io/language-counter.ts`
- [Token utils](https://github.com/swark-io/swark/blob/main/src/llm/token-count-utils.ts): budgeting · Token counting helpers used to fit context limits · `src/llm/token-count-utils.ts`

### LLM pipeline

Prompting and Copilot model interaction

- [Prompt builder](https://github.com/swark-io/swark/blob/main/src/llm/prompt-builder.ts): prompting · Turns selected files into a structured model prompt · `src/llm/prompt-builder.ts`
- [Model interactor](https://github.com/swark-io/swark/blob/main/src/llm/model-interactor.ts): copilot-api · Calls the VS Code Language Model API via GitHub Copilot · `src/llm/model-interactor.ts`
- [Debug utils](https://github.com/swark-io/swark/blob/main/src/llm/debug-utils.ts): diagnostics · Supports logging and inspection of prompt and response behavior · `src/llm/debug-utils.ts`

### Diagram output

Mermaid normalization, markdown assembly, and preview

- [Mermaid serde](https://github.com/swark-io/swark/blob/main/src/view/mermaid/serde.ts): normalization · Parses and serializes Mermaid-oriented diagram content · `src/view/mermaid/serde.ts`
- [Link generator](https://github.com/swark-io/swark/blob/main/src/view/mermaid/link-generator.ts): normalization · Builds Mermaid links used in the generated diagram · `src/view/mermaid/link-generator.ts`
- [Cycle detector](https://github.com/swark-io/swark/blob/main/src/view/mermaid/cycle-detector.ts): repair · Detects or fixes Mermaid cycles that can break rendering · `src/view/mermaid/cycle-detector.ts`
- [Output formatter](https://github.com/swark-io/swark/blob/main/src/view/output-formatter.ts): markdown · Assembles final markdown with Mermaid and logs · `src/view/output-formatter.ts`
- [Output writer](https://github.com/swark-io/swark/blob/main/src/view/output-writer.ts): persistence · Writes diagram and log markdown into the workspace output folder · `src/view/output-writer.ts`
- [Viewer](https://github.com/swark-io/swark/blob/main/src/view/viewer.ts): preview · Opens the generated markdown for in-editor preview · `src/view/viewer.ts`

### Observability

Telemetry and debug support

- [Telemetry](https://github.com/swark-io/swark/blob/main/src/telemetry.ts): events · Collects privacy-preserving usage and error events · `src/telemetry.ts`

## Connections

- Extension → Create arch: registers · Activation wires the main command
- Create arch → Scope picker: select scope · Command asks the user for the target workspace slice
- Scope picker → Repo reader: scope · Selected folder drives repository ingestion
- Repo reader → Language count: measure · Reader estimates content size before expanding context
- Language count → Token utils: budget · Language sizing feeds token budgeting
- Token utils → Repo reader: limit files · Token budget constrains how many files are loaded
- Repo reader → Prompt builder: files · Curated source files are handed to prompt construction
- Prompt builder → Model interactor: prompt · Structured prompt is sent to the model interactor
- Debug utils → Model interactor: inspect · Debug support observes request and response behavior
- Model interactor → Mermaid serde: diagram · Model output is normalized as Mermaid-like content
- Mermaid serde → Link generator: linkify · Serialized diagram content gets link generation support
- Link generator → Cycle detector: validate · Link structure is checked for cycle issues
- Cycle detector → Output formatter: repair · Repaired Mermaid is assembled into final markdown
- Output formatter → Output writer: persist · Formatted output is written to workspace files
- Output writer → Viewer: preview · Written markdown is opened in the VS Code viewer
- Create arch → Telemetry: emit events · The command reports timing, usage, and errors
