# shchusia/commit-hike architecture

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

- Interactive diagram: https://gitdiagram.com/shchusia/commit-hike
- Repository: https://github.com/shchusia/commit-hike

## Overview

Commit Hike is an offline IDE hiking-progress application: commits advance a hiker along a chosen route, with scenes, maps, stories, stats, achievements, and optional project teammates. The main flow runs from an IDE plugin through the CLI and app service; the service reads Git history, filters and scores commits, updates local progress, and returns protocol data for the plugin UI. Route import, rendering, and team views are distinct capabilities. The README describes maps and route-pack richness; their detailed implementation is not sampled here, so links are limited to supported app and package boundaries.

Main entry points: [`core/internal/app/app.go`](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/app.go) (Use-case service), [`plugins/vscode/src/extension.ts`](https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/extension.ts) (VS Code extension), [`core/internal/app/scan.go`](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/scan.go) (Commit scanning), [`core/cmd/commit-hike/main.go`](https://github.com/shchusia/commit-hike/blob/master/core/cmd/commit-hike/main.go) (Core command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ide["IDE plugins"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
  node_vscode_cli["VS Code CLI<br/>[cli.ts]"]
  node_vscode_ui["VS Code panel<br/>[panel.ts]"]
  node_vscode_i18n["VS Code language<br/>[i18n.ts]"]
  node_jetbrains["JetBrains plugin<br/>[CommitHikeApp.kt]"]
  node_jetbrains_actions["JetBrains actions<br/>[Actions.kt]"]
  node_jetbrains_cli["JetBrains CLI<br/>[CoreCli.kt]"]
  node_jetbrains_ui["JetBrains trail UI<br/>[TrailUi.kt]"]
end

subgraph group_engine["Progress engine"]
  node_engine_bin["Core command<br/>[main.go]"]
  node_cli["Command dispatcher<br/>[cli.go]"]
  node_app["Use-case service<br/>[app.go]"]
  node_scan["Commit scanning<br/>[scan.go]"]
  node_journey["Journey progress<br/>[journey.go]"]
  node_team["Team view<br/>[team.go]"]
  node_protocol["JSON contract<br/>[protocol.go]"]
  node_gitlog["Git history reader<br/>[gitlog.go]"]
  node_filter["Commit filtering<br/>[filter.go]"]
  node_score["Distance scoring<br/>[score.go]"]
  node_achievements["Achievements<br/>[achievements.go]"]
end

subgraph group_routes["Routes and scenes"]
  node_route_service["Route management<br/>[routes.go]"]
  node_route_loader["Route packs<br/>[routes.go]"]
  node_renderer["Scene renderer<br/>[render.go]"]
  node_embed["Embedded content<br/>[embed.go]"]
end

subgraph group_state["Local data"]
  node_store[("Progress store<br/>[store.go]")]
end

node_vscode_actor(("VS Code user"))
node_jetbrains_actor(("JetBrains user"))
node_git[("Local Git repository")]

node_vscode_actor -->|"uses"| node_vscode
node_vscode -->|"invokes"| node_vscode_cli
node_vscode -->|"updates"| node_vscode_ui
node_vscode -->|"localizes"| node_vscode_i18n
node_vscode_cli -->|"runs"| node_engine_bin
node_jetbrains_actor -->|"uses"| node_jetbrains
node_jetbrains -->|"dispatches"| node_jetbrains_actions
node_jetbrains -->|"shows"| node_jetbrains_ui
node_jetbrains_actions -->|"invokes"| node_jetbrains_cli
node_jetbrains_cli -->|"runs"| node_engine_bin
node_engine_bin -->|"starts"| node_cli
node_cli -->|"dispatches"| node_app
node_cli -->|"encodes"| node_protocol
node_app -->|"handles scans"| node_scan
node_app -->|"serves journeys"| node_journey
node_app -->|"serves teams"| node_team
node_app -->|"manages routes"| node_route_service
node_scan -->|"reads history"| node_gitlog
node_scan -->|"filters commits"| node_filter
node_scan -->|"scores distance"| node_score
node_scan -->|"updates progress"| node_store
node_journey -->|"reads and writes"| node_store
node_team -->|"reads contributors"| node_gitlog
node_team -->|"reads settings"| node_store
node_app -->|"evaluates goals"| node_achievements
node_route_service -->|"loads packs"| node_route_loader
node_route_service -->|"persists imports"| node_store
node_app -->|"builds scenes"| node_renderer
node_route_loader -->|"loads built-ins"| node_embed
node_gitlog -->|"reads history"| node_git
node_vscode -->|"requests status"| node_engine_bin
node_jetbrains -->|"requests status"| node_engine_bin

click node_vscode "https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/extension.ts"
click node_vscode_cli "https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/cli.ts"
click node_vscode_ui "https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/panel.ts"
click node_vscode_i18n "https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/i18n.ts"
click node_jetbrains "https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/CommitHikeApp.kt"
click node_jetbrains_actions "https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/actions/Actions.kt"
click node_jetbrains_cli "https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/core/CoreCli.kt"
click node_jetbrains_ui "https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/ui/TrailUi.kt"
click node_engine_bin "https://github.com/shchusia/commit-hike/blob/master/core/cmd/commit-hike/main.go"
click node_cli "https://github.com/shchusia/commit-hike/blob/master/core/internal/cli/cli.go"
click node_app "https://github.com/shchusia/commit-hike/blob/master/core/internal/app/app.go"
click node_scan "https://github.com/shchusia/commit-hike/blob/master/core/internal/app/scan.go"
click node_journey "https://github.com/shchusia/commit-hike/blob/master/core/internal/app/journey.go"
click node_team "https://github.com/shchusia/commit-hike/blob/master/core/internal/app/team.go"
click node_protocol "https://github.com/shchusia/commit-hike/blob/master/core/internal/protocol/protocol.go"
click node_gitlog "https://github.com/shchusia/commit-hike/blob/master/core/internal/gitlog/gitlog.go"
click node_filter "https://github.com/shchusia/commit-hike/blob/master/core/internal/filter/filter.go"
click node_score "https://github.com/shchusia/commit-hike/blob/master/core/internal/score/score.go"
click node_achievements "https://github.com/shchusia/commit-hike/blob/master/core/internal/achievements/achievements.go"
click node_route_service "https://github.com/shchusia/commit-hike/blob/master/core/internal/app/routes.go"
click node_route_loader "https://github.com/shchusia/commit-hike/blob/master/core/internal/routes/routes.go"
click node_renderer "https://github.com/shchusia/commit-hike/blob/master/core/internal/render/render.go"
click node_embed "https://github.com/shchusia/commit-hike/blob/master/core/content/embed.go"
click node_store "https://github.com/shchusia/commit-hike/blob/master/core/internal/store/store.go"

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_vscode,node_vscode_cli,node_vscode_ui,node_vscode_i18n,node_jetbrains,node_jetbrains_actions,node_jetbrains_cli,node_jetbrains_ui,node_vscode_actor,node_jetbrains_actor toneBlue
class node_engine_bin,node_cli,node_app,node_scan,node_journey,node_team,node_protocol,node_gitlog,node_filter,node_score,node_achievements,node_git toneAmber
class node_route_service,node_route_loader,node_renderer,node_embed toneMint
class node_store toneRose
```

## Components

### IDE plugins

- [VS Code extension](https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/extension.ts): `plugins/vscode/src/extension.ts`
- [VS Code CLI](https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/cli.ts): `plugins/vscode/src/cli.ts`
- [VS Code panel](https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/panel.ts): `plugins/vscode/src/panel.ts`
- [VS Code language](https://github.com/shchusia/commit-hike/blob/master/plugins/vscode/src/i18n.ts): `plugins/vscode/src/i18n.ts`
- [JetBrains plugin](https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/CommitHikeApp.kt): `plugins/jetbrains/src/main/kotlin/dev/commithike/CommitHikeApp.kt`
- [JetBrains actions](https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/actions/Actions.kt): `plugins/jetbrains/src/main/kotlin/dev/commithike/actions/Actions.kt`
- [JetBrains CLI](https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/core/CoreCli.kt): `plugins/jetbrains/src/main/kotlin/dev/commithike/core/CoreCli.kt`
- [JetBrains trail UI](https://github.com/shchusia/commit-hike/blob/master/plugins/jetbrains/src/main/kotlin/dev/commithike/ui/TrailUi.kt): `plugins/jetbrains/src/main/kotlin/dev/commithike/ui/TrailUi.kt`

### Progress engine

- [Core command](https://github.com/shchusia/commit-hike/blob/master/core/cmd/commit-hike/main.go): `core/cmd/commit-hike/main.go`
- [Command dispatcher](https://github.com/shchusia/commit-hike/blob/master/core/internal/cli/cli.go): `core/internal/cli/cli.go`
- [Use-case service](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/app.go): `core/internal/app/app.go`
- [Commit scanning](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/scan.go): `core/internal/app/scan.go`
- [Journey progress](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/journey.go): `core/internal/app/journey.go`
- [Team view](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/team.go): `core/internal/app/team.go`
- [JSON contract](https://github.com/shchusia/commit-hike/blob/master/core/internal/protocol/protocol.go): `core/internal/protocol/protocol.go`
- [Git history reader](https://github.com/shchusia/commit-hike/blob/master/core/internal/gitlog/gitlog.go): `core/internal/gitlog/gitlog.go`
- [Commit filtering](https://github.com/shchusia/commit-hike/blob/master/core/internal/filter/filter.go): `core/internal/filter/filter.go`
- [Distance scoring](https://github.com/shchusia/commit-hike/blob/master/core/internal/score/score.go): `core/internal/score/score.go`
- [Achievements](https://github.com/shchusia/commit-hike/blob/master/core/internal/achievements/achievements.go): `core/internal/achievements/achievements.go`

### Routes and scenes

- [Route management](https://github.com/shchusia/commit-hike/blob/master/core/internal/app/routes.go): `core/internal/app/routes.go`
- [Route packs](https://github.com/shchusia/commit-hike/blob/master/core/internal/routes/routes.go): `core/internal/routes/routes.go`
- [Scene renderer](https://github.com/shchusia/commit-hike/blob/master/core/internal/render/render.go): `core/internal/render/render.go`
- [Embedded content](https://github.com/shchusia/commit-hike/blob/master/core/content/embed.go): `core/content/embed.go`

### Local data

- [Progress store](https://github.com/shchusia/commit-hike/blob/master/core/internal/store/store.go): `core/internal/store/store.go`

### Other components

- **VS Code user**
- **JetBrains user**
- **Local Git repository**

## Connections

- VS Code user → VS Code extension: uses
- VS Code extension → VS Code CLI: invokes
- VS Code extension → VS Code panel: updates
- VS Code extension → VS Code language: localizes
- VS Code CLI → Core command: runs
- JetBrains user → JetBrains plugin: uses
- JetBrains plugin → JetBrains actions: dispatches
- JetBrains plugin → JetBrains trail UI: shows
- JetBrains actions → JetBrains CLI: invokes
- JetBrains CLI → Core command: runs
- Core command → Command dispatcher: starts
- Command dispatcher → Use-case service: dispatches
- Command dispatcher → JSON contract: encodes
- Use-case service → Commit scanning: handles scans
- Use-case service → Journey progress: serves journeys
- Use-case service → Team view: serves teams
- Use-case service → Route management: manages routes
- Commit scanning → Git history reader: reads history
- Commit scanning → Commit filtering: filters commits
- Commit scanning → Distance scoring: scores distance
- Commit scanning → Progress store: updates progress
- Journey progress → Progress store: reads and writes
- Team view → Git history reader: reads contributors
- Team view → Progress store: reads settings
- Use-case service → Achievements: evaluates goals
- Route management → Route packs: loads packs
- Route management → Progress store: persists imports
- Use-case service → Scene renderer: builds scenes
- Route packs → Embedded content: loads built-ins
- Git history reader → Local Git repository: reads history
- VS Code extension → Core command: requests status
- JetBrains plugin → Core command: requests status