How It Works

GitScrum Studio extends your code editor with project management panels that behave like native editor tabs. This guide explains the architecture, navigation model, and how data flows between the extension and GitScrum.

The Extension Structure

GitScrum Studio adds three integration points to your editor:

1. Activity Bar → GitScrum Icon → Sidebar Tree
2. Editor Area → Webview Panels (tabs)
3. Status Bar → Persistent Timer

These three elements work together. The sidebar is your navigation hub. Panels are your workspace. The timer tracks time independently of both.

The Sidebar Tree

Clicking the GitScrum icon in the Activity Bar opens a tree-view sidebar. It organizes your data in a clear hierarchy:

Workspace Name
  └─ Project Name
       ├─ Plan
       │    ├─ Sprints
       │    ├─ User Stories
       │    └─ Team Standup
       ├─ Build
       │    └─ Board
       ├─ Knowledge
       │    ├─ Wiki
       │    ├─ Discussions
       │    └─ Documents
       └─ Time Tracking

Workspace Level

The top-level nodes represent your GitScrum workspaces (organizations). Each workspace contains the projects you have access to based on your role.

Project Level

Expanding a workspace reveals its projects. Clicking a project sets it as active — this determines which data all panels display.

Feature Groups

Each project organizes its features into three logical groups:

Time Tracking sits at the project root level since it spans all other features.

Webview Panels

Clicking any sidebar item opens a webview panel in the editor area. These panels:

• Render as editor tabs — move, split, pin, or close them like any file tab
• Display rich interfaces — Kanban boards, charts, forms, and tables
• Communicate bidirectionally — actions in the panel trigger API calls; data from the API updates the panel
• Refresh automatically — at the configured interval (default: 5 minutes)

Panel Lifecycle

1. Click sidebar item → panel opens (or focuses if already open)
2. Panel loads data from the GitScrum API
3. User interacts → actions send messages to the extension
4. Extension processes → calls API, updates panel with results
5. Auto-refresh → periodic data reload in the background

Panel Reuse

Panels are keyed by workspace and project. Opening the Board for the same project twice focuses the existing panel instead of creating a duplicate. Opening the Board for a different project creates a new panel.

The Status Bar Timer

A clock icon sits in the status bar at the bottom of your editor. It is always visible, regardless of which panel or file is active.

Timer States

Timer Persistence

The timer saves its state to the editor's global storage every 60 seconds. This means:

• Close the editor → timer continues when you reopen
• Restart your computer → timer resumes from last saved state
• Server sync → on startup, the extension checks the server for an active timer and synchronizes

QuickPick Menu

Clicking the status bar timer opens a QuickPick menu with context-dependent options:

When idle:

• ▶ Start Timer — opens a task picker
• 📜 View Time Entries — opens the Time Tracking panel
• 📊 Open Time Tracking Panel — opens analytics

When active:

• ⏹ Stop Timer — logs the time entry with optional comment
• 🔄 Switch Task — stops current timer, starts a new one
• 🗑 Discard Timer — cancels without saving
• 📜 View Time Entries
• 📊 Open Time Tracking Panel

Data Flow

All data flows through the GitScrum REST API. The extension is a client — it reads and writes data through authenticated HTTP requests.

Editor Panel → Extension Backend → GitScrum API → Database
     ↑              ↓
     └── Response ──┘

Authentication

The extension stores your authentication token using the editor's SecretStorage API. Every API request includes this token. When the token expires or you sign out, the sidebar shows sign-in options.

API Communication

Each panel has a dedicated service class that handles its API calls:

Auto-Refresh

Panels refresh automatically at a regular interval. Click the refresh button in any panel header for an immediate update.

The Task Drawer

The task drawer is a shared component that appears in multiple panels — Board, Sprints, User Stories, and Time Tracking. When you click a task in any of these panels, the drawer opens as a side panel with full editing capabilities:

The drawer provides a consistent editing experience regardless of which panel you opened the task from.

Role-Based Access

The extension respects your GitScrum workspace role. What you see and can do depends on your permissions:

Some actions — like opening Project Settings from the sidebar — are only available to Agency Owners. If a feature appears disabled, verify your role in the GitScrum web application.

Command Palette

Every feature is accessible from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Type GitScrum: to see all commands:

You can bind custom keyboard shortcuts to any of these commands through the Keyboard Shortcuts editor (Ctrl+K Ctrl+S / Cmd+K Cmd+S).

Related Documentation

• Quickstart — Install and configure in 2 minutes
• Getting Started — Full setup with all authentication options
• Kanban Board — Deep dive into board features
• Time Tracking — Timer workflows and analytics