# rubyazz/akatsuki-git architecture

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

- Interactive diagram: https://gitdiagram.com/rubyazz/akatsuki-git
- Repository: https://github.com/rubyazz/akatsuki-git

## Overview

Akatsuki Git is a VS Code extension backed by a Rust sidecar. Its main workflow detects repository changes, analyzes commit history, derives a shinobi rank, and presents themed progress in the extension. Onboarding stores a character path and profile; event messages and dashboard/status-bar views add separate user-facing features. The excerpts establish the RPC dispatch, repository analysis, and persistence paths; some feature wiring is documented by the README but its implementation was not sampled, so those links are limited.

Main entry points: [`extension/src/extension.ts`](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/extension.ts) (Extension lifecycle), [`extension/src/backendClient.ts`](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/backendClient.ts) (Backend client), [`backend/src/handlers.rs`](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/handlers.rs) (RPC handlers), [`backend/src/main.rs`](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/main.rs) (Backend runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vscode["VS Code experience"]
  node_extension["Extension lifecycle<br/>[extension.ts]"]
  node_watcher["Change detection<br/>[gitWatcher.ts]"]
  node_onboarding["Profile onboarding<br/>[onboarding.ts]"]
  node_status["Rank status<br/>[statusBar.ts]"]
  node_dashboard["Progress dashboard<br/>[dashboard.ts]"]
  node_messages["Themed messages<br/>[messages.ts]"]
end

subgraph group_ipc["RPC boundary"]
  node_client["Backend client<br/>[backendClient.ts]"]
  node_protocol["RPC protocol<br/>[protocol.ts]"]
end

subgraph group_backend["Progress backend"]
  node_backend["Backend runtime<br/>[main.rs]"]
  node_handlers["RPC handlers<br/>[handlers.rs]"]
  node_analyzer["Git analysis<br/>[git_analyzer.rs]"]
  node_ranks["Rank calculation<br/>[ranks.rs]"]
  node_templates["Character templates<br/>[paths.rs]"]
end

subgraph group_state["Progress state"]
  node_storage[("Profile and stats<br/>[storage.rs]")]
end

node_developer(("Developer"))
node_gitrepo[("Git repository")]

node_developer -->|"uses"| node_extension
node_gitrepo -->|"signals changes"| node_watcher
node_watcher -->|"triggers refresh"| node_extension
node_extension -->|"sends requests"| node_client
node_onboarding -->|"manages profile"| node_client
node_messages -->|"requests templates"| node_client
node_client -->|"JSON-RPC over stdio"| node_backend
node_backend -->|"returns responses"| node_client
node_backend -->|"follows contract"| node_protocol
node_client -->|"uses types"| node_protocol
node_backend -->|"dispatches requests"| node_handlers
node_handlers -->|"analyzes repository"| node_analyzer
node_handlers -->|"calculates rank"| node_ranks
node_handlers -->|"gets messages"| node_templates
node_handlers -->|"reads and writes"| node_storage
node_analyzer -->|"reads history"| node_gitrepo
node_extension -->|"updates display"| node_status
node_extension -->|"provides stats and rank"| node_dashboard
node_extension -->|"uses notifications"| node_messages

click node_extension "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/extension.ts"
click node_watcher "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/gitWatcher.ts"
click node_onboarding "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/onboarding.ts"
click node_status "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/statusBar.ts"
click node_dashboard "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/dashboard.ts"
click node_messages "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/messages.ts"
click node_client "https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/backendClient.ts"
click node_protocol "https://github.com/rubyazz/akatsuki-git/blob/main/shared/ts/protocol.ts"
click node_backend "https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/main.rs"
click node_handlers "https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/handlers.rs"
click node_analyzer "https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/git_analyzer.rs"
click node_ranks "https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/ranks.rs"
click node_templates "https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/paths.rs"
click node_storage "https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/storage.rs"

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_extension,node_watcher,node_onboarding,node_status,node_dashboard,node_messages toneBlue
class node_client,node_protocol,node_gitrepo toneAmber
class node_backend,node_handlers,node_analyzer,node_ranks,node_templates toneMint
class node_storage toneRose
class node_developer toneIndigo
```

## Components

### VS Code experience

- [Extension lifecycle](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/extension.ts): `extension/src/extension.ts`
- [Change detection](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/gitWatcher.ts): `extension/src/gitWatcher.ts`
- [Profile onboarding](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/onboarding.ts): `extension/src/onboarding.ts`
- [Rank status](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/statusBar.ts): `extension/src/statusBar.ts`
- [Progress dashboard](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/dashboard.ts): `extension/src/dashboard.ts`
- [Themed messages](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/messages.ts): `extension/src/messages.ts`

### RPC boundary

- [Backend client](https://github.com/rubyazz/akatsuki-git/blob/main/extension/src/backendClient.ts): `extension/src/backendClient.ts`
- [RPC protocol](https://github.com/rubyazz/akatsuki-git/blob/main/shared/ts/protocol.ts): `shared/ts/protocol.ts`

### Progress backend

- [Backend runtime](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/main.rs): `backend/src/main.rs`
- [RPC handlers](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/handlers.rs): `backend/src/handlers.rs`
- [Git analysis](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/git_analyzer.rs): `backend/src/git_analyzer.rs`
- [Rank calculation](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/ranks.rs): `backend/src/ranks.rs`
- [Character templates](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/paths.rs): `backend/src/paths.rs`

### Progress state

- [Profile and stats](https://github.com/rubyazz/akatsuki-git/blob/main/backend/src/storage.rs): `backend/src/storage.rs`

### Other components

- **Developer**
- **Git repository**

## Connections

- Developer → Extension lifecycle: uses
- Git repository → Change detection: signals changes
- Change detection → Extension lifecycle: triggers refresh
- Extension lifecycle → Backend client: sends requests
- Profile onboarding → Backend client: manages profile
- Themed messages → Backend client: requests templates
- Backend client → Backend runtime: JSON-RPC over stdio
- Backend runtime → Backend client: returns responses
- Backend runtime → RPC protocol: follows contract
- Backend client → RPC protocol: uses types
- Backend runtime → RPC handlers: dispatches requests
- RPC handlers → Git analysis: analyzes repository
- RPC handlers → Rank calculation: calculates rank
- RPC handlers → Character templates: gets messages
- RPC handlers → Profile and stats: reads and writes
- Git analysis → Git repository: reads history
- Extension lifecycle → Rank status: updates display
- Extension lifecycle → Progress dashboard: provides stats and rank
- Extension lifecycle → Themed messages: uses notifications