# asedunov/intellij-crystal-lang architecture

> Architecture diagram of the GitHub repository asedunov/intellij-crystal-lang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asedunov/intellij-crystal-lang
- Repository: https://github.com/asedunov/intellij-crystal-lang

## Overview

This repository is an IntelliJ plugin for Crystal language support. The main user workflow is editing Crystal source: IntelliJ supplies file/editor events, language tooling parses source into PSI, and IDE features act on that PSI for navigation, feedback, and code assistance. The tree also documents run configurations, formatting, project setup, and Shards YAML support. Source excerpts are limited, so several capability nodes are grounded in the tree but their internal links are left unverified rather than inferred.

Main entry points: [`src/main/kotlin/org/crystal/intellij/lang/psi/CrFile.kt`](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/psi/CrFile.kt) (Crystal PSI), [`src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt`](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt) (Symbol Resolution), [`src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt`](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt) (Crystal Parser), [`src/main/kotlin/org/crystal/intellij/ide/structure/CrystalStructureViewElement.kt`](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/structure/CrystalStructureViewElement.kt) (Structure View)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Front End"]
  node_lexer["Crystal Lexer<br/>[CrystalLexer.kt]"]
  node_parser["Crystal Parser<br/>[CrystalParser.kt]"]
  node_lazybuilder["Lazy PSI Builder"]
  node_psi["Crystal PSI<br/>[CrFile.kt]"]
  node_filefragment["File Fragments<br/>[CrFileFragment.kt]"]
  node_stubs["PSI Stubs"]
end

subgraph group_analysis["Resolution and Feedback"]
  node_resolver["Symbol Resolution<br/>[CrModuleLikeSym.kt]"]
  node_resolvecache[("Resolve Cache<br/>[CrResolveCache.kt]")]
  node_scopes["Module Scopes"]
  node_highlight["Syntax and Resolve Feedback"]
end

subgraph group_editing["Editor Assistance"]
  node_completion["Code Completion"]
  node_editorhandlers["Editor Handlers"]
  node_formatting["Code Formatting"]
end

subgraph group_ide["IDE Workflows"]
  node_structure["Structure View"]
  node_navigation["Navigation and Search"]
  node_refactoring["Rename Refactoring"]
end

subgraph group_project["Project Integrations"]
  node_run["Run Configurations"]
  node_projectsetup["Project Setup"]
  node_shards["Shards YAML Support<br/>[ShardYamlSchema.kt]"]
end

node_developer(("Crystal Developer"))
node_intellij["IntelliJ Platform"]
node_crystaltool["Crystal Tool"]

node_developer -->|"uses IDE"| node_intellij
node_intellij -.->|"opens source"| node_lexer
node_lexer -->|"supplies tokens"| node_parser
node_parser -->|"builds with"| node_lazybuilder
node_parser -.->|"creates PSI"| node_psi
node_psi -->|"exposes fragments"| node_filefragment
node_filefragment -->|"uses stub API"| node_stubs
node_psi -.->|"provides symbols"| node_resolver
node_resolver -->|"caches resolution"| node_resolvecache
node_resolver -->|"builds scopes"| node_scopes
node_psi -.->|"analyzes source"| node_highlight
node_intellij -->|"dispatches typing"| node_editorhandlers
node_editorhandlers -->|"queries PSI"| node_psi
node_intellij -.->|"requests completion"| node_completion
node_completion -.->|"resolves candidates"| node_resolver
node_intellij -.->|"requests formatting"| node_formatting
node_formatting -.->|"formats externally"| node_crystaltool
node_intellij -.->|"opens structure view"| node_structure
node_structure -->|"traverses PSI"| node_psi
node_structure -.->|"presents definitions"| node_navigation
node_intellij -.->|"requests navigation"| node_navigation
node_intellij -.->|"invokes rename"| node_refactoring
node_refactoring -.->|"renames symbols"| node_psi
node_intellij -.->|"starts configuration"| node_run
node_run -.->|"runs Crystal"| node_crystaltool
node_intellij -.->|"creates project"| node_projectsetup
node_intellij -.->|"inspects manifest"| node_shards

click node_lexer "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/lexer/CrystalLexer.kt"
click node_parser "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt"
click node_lazybuilder "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/java/org/crystal/intellij/parser/builder/LazyPsiBuilder.java"
click node_psi "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/psi/CrFile.kt"
click node_filefragment "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/psi/CrFileFragment.kt"
click node_stubs "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/stubs/api/CrFileFragmentStub.kt"
click node_resolver "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt"
click node_resolvecache "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/cache/CrResolveCache.kt"
click node_scopes "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/scopes/CrModuleLikeScope.kt"
click node_highlight "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/highlighter/CrystalSyntaxCheckingPass.kt"
click node_completion "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/completion/CrKeywordCompletionContributor.kt"
click node_editorhandlers "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/editor/CrystalTypedHandler.kt"
click node_formatting "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/formatter/CrystalFormattingModelBuilder.kt"
click node_structure "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/structure/CrystalStructureViewElement.kt"
click node_navigation "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/navigation/CrystalChooseByNameContributor.kt"
click node_refactoring "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/refactoring/rename/CrystalRenameHandler.kt"
click node_run "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/run/CrystalFileRunState.kt"
click node_projectsetup "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/config/project/CrystalDirectoryProjectGenerator.kt"
click node_shards "https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/shards/yaml/model/ShardYamlSchema.kt"

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_lexer,node_parser,node_lazybuilder,node_psi,node_filefragment,node_stubs toneBlue
class node_resolver,node_resolvecache,node_scopes,node_highlight toneAmber
class node_completion,node_editorhandlers,node_formatting toneMint
class node_structure,node_navigation,node_refactoring toneRose
class node_run,node_projectsetup,node_shards,node_developer,node_intellij,node_crystaltool toneIndigo
```

## Components

### Language Front End

- [Crystal Lexer](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/lexer/CrystalLexer.kt): `src/main/kotlin/org/crystal/intellij/lang/lexer/CrystalLexer.kt`
- [Crystal Parser](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt): `src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt`
- [Lazy PSI Builder](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/java/org/crystal/intellij/parser/builder/LazyPsiBuilder.java): `src/main/java/org/crystal/intellij/parser/builder/LazyPsiBuilder.java`
- [Crystal PSI](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/psi/CrFile.kt): `src/main/kotlin/org/crystal/intellij/lang/psi/CrFile.kt`
- [File Fragments](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/psi/CrFileFragment.kt): `src/main/kotlin/org/crystal/intellij/lang/psi/CrFileFragment.kt`
- [PSI Stubs](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/stubs/api/CrFileFragmentStub.kt): `src/main/kotlin/org/crystal/intellij/lang/stubs/api/CrFileFragmentStub.kt`

### Resolution and Feedback

- [Symbol Resolution](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt): `src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt`
- [Resolve Cache](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/cache/CrResolveCache.kt): `src/main/kotlin/org/crystal/intellij/lang/resolve/cache/CrResolveCache.kt`
- [Module Scopes](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/lang/resolve/scopes/CrModuleLikeScope.kt): `src/main/kotlin/org/crystal/intellij/lang/resolve/scopes/CrModuleLikeScope.kt`
- [Syntax and Resolve Feedback](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/highlighter/CrystalSyntaxCheckingPass.kt): `src/main/kotlin/org/crystal/intellij/ide/highlighter/CrystalSyntaxCheckingPass.kt`

### Editor Assistance

- [Code Completion](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/completion/CrKeywordCompletionContributor.kt): `src/main/kotlin/org/crystal/intellij/ide/completion/CrKeywordCompletionContributor.kt`
- [Editor Handlers](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/editor/CrystalTypedHandler.kt): `src/main/kotlin/org/crystal/intellij/ide/editor/CrystalTypedHandler.kt`
- [Code Formatting](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/formatter/CrystalFormattingModelBuilder.kt): `src/main/kotlin/org/crystal/intellij/ide/formatter/CrystalFormattingModelBuilder.kt`

### IDE Workflows

- [Structure View](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/structure/CrystalStructureViewElement.kt): `src/main/kotlin/org/crystal/intellij/ide/structure/CrystalStructureViewElement.kt`
- [Navigation and Search](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/navigation/CrystalChooseByNameContributor.kt): `src/main/kotlin/org/crystal/intellij/ide/navigation/CrystalChooseByNameContributor.kt`
- [Rename Refactoring](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/refactoring/rename/CrystalRenameHandler.kt): `src/main/kotlin/org/crystal/intellij/ide/refactoring/rename/CrystalRenameHandler.kt`

### Project Integrations

- [Run Configurations](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/run/CrystalFileRunState.kt): `src/main/kotlin/org/crystal/intellij/ide/run/CrystalFileRunState.kt`
- [Project Setup](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/config/project/CrystalDirectoryProjectGenerator.kt): `src/main/kotlin/org/crystal/intellij/ide/config/project/CrystalDirectoryProjectGenerator.kt`
- [Shards YAML Support](https://github.com/asedunov/intellij-crystal-lang/blob/master/src/main/kotlin/org/crystal/intellij/ide/shards/yaml/model/ShardYamlSchema.kt): `src/main/kotlin/org/crystal/intellij/ide/shards/yaml/model/ShardYamlSchema.kt`

### Other components

- **Crystal Developer**
- **IntelliJ Platform**
- **Crystal Tool**

## Connections

- Crystal Developer → IntelliJ Platform: uses IDE
- IntelliJ Platform → Crystal Lexer: opens source
- Crystal Lexer → Crystal Parser: supplies tokens (evidence: `src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt`)
- Crystal Parser → Lazy PSI Builder: builds with (evidence: `src/main/kotlin/org/crystal/intellij/lang/parser/CrystalParser.kt`)
- Crystal Parser → Crystal PSI: creates PSI
- Crystal PSI → File Fragments: exposes fragments (evidence: `src/main/kotlin/org/crystal/intellij/lang/psi/CrFile.kt`)
- File Fragments → PSI Stubs: uses stub API (evidence: `src/main/kotlin/org/crystal/intellij/lang/psi/CrFileFragment.kt`)
- Crystal PSI → Symbol Resolution: provides symbols
- Symbol Resolution → Resolve Cache: caches resolution (evidence: `src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt`)
- Symbol Resolution → Module Scopes: builds scopes (evidence: `src/main/kotlin/org/crystal/intellij/lang/resolve/symbols/CrModuleLikeSym.kt`)
- Crystal PSI → Syntax and Resolve Feedback: analyzes source
- IntelliJ Platform → Editor Handlers: dispatches typing (evidence: `src/main/kotlin/org/crystal/intellij/ide/editor/CrystalTypedHandler.kt`)
- Editor Handlers → Crystal PSI: queries PSI (evidence: `src/main/kotlin/org/crystal/intellij/ide/editor/CrystalTypedHandler.kt`)
- IntelliJ Platform → Code Completion: requests completion
- Code Completion → Symbol Resolution: resolves candidates
- IntelliJ Platform → Code Formatting: requests formatting
- Code Formatting → Crystal Tool: formats externally
- IntelliJ Platform → Structure View: opens structure view
- Structure View → Crystal PSI: traverses PSI (evidence: `src/main/kotlin/org/crystal/intellij/ide/structure/CrystalStructureViewElement.kt`)
- Structure View → Navigation and Search: presents definitions
- IntelliJ Platform → Navigation and Search: requests navigation
- IntelliJ Platform → Rename Refactoring: invokes rename
- Rename Refactoring → Crystal PSI: renames symbols
- IntelliJ Platform → Run Configurations: starts configuration
- Run Configurations → Crystal Tool: runs Crystal
- IntelliJ Platform → Project Setup: creates project
- IntelliJ Platform → Shards YAML Support: inspects manifest