# Extensions (IDE Plugins) Architecture

> Technical architecture for VS Code and JetBrains IDE plugins providing Stella Ops integration.

## Overview

The Extensions module consists of two independent IDE plugins that provide developer-facing integration with the Stella Ops platform. Both plugins are pure HTTP clients that consume the Orchestrator and Router APIs; they do not host any services, expose endpoints, or maintain local databases. Authentication is handled through OAuth tokens obtained from the Authority service.

## Design Principles

1. **Thin client** - Extensions contain no business logic; all state and decisions live in backend services
2. **Consistent experience** - Both plugins expose equivalent functionality despite different technology stacks
3. **Non-blocking** - All API calls are asynchronous; the IDE remains responsive during network operations
4. **Offline-tolerant** - Graceful degradation when the Stella Ops backend is unreachable

## Components

```
Extensions/
├── vscode-stella-ops/                    # VS Code extension (TypeScript)
│   ├── src/
│   │   ├── extension.ts                  # Entry point and activation
│   │   ├── providers/
│   │   │   ├── ReleaseTreeProvider.ts    # TreeView: releases
│   │   │   ├── EnvironmentTreeProvider.ts# TreeView: environments
│   │   │   └── CodeLensProvider.ts       # CodeLens for stella.yaml
│   │   ├── commands/                     # Command palette handlers
│   │   ├── views/
│   │   │   └── webview/                  # Webview panels (detail views)
│   │   ├── statusbar/
│   │   │   └── StatusBarManager.ts       # Status bar integration
│   │   └── api/
│   │       └── OrchestratorClient.ts     # HTTP client for Orchestrator API
│   ├── package.json                      # Extension manifest
│   └── tsconfig.json
│
└── jetbrains-stella-ops/                 # JetBrains plugin (Kotlin)
    ├── src/main/kotlin/
    │   ├── toolwindow/
    │   │   ├── ReleasesToolWindow.kt     # Tool window: Releases tab
    │   │   ├── EnvironmentsToolWindow.kt # Tool window: Environments tab
    │   │   └── DeploymentsToolWindow.kt  # Tool window: Deployments tab
    │   ├── annotator/
    │   │   └── StellaYamlAnnotator.kt    # YAML file annotator
    │   ├── actions/                      # Action menu handlers
    │   ├── statusbar/
    │   │   └── StellaStatusBarWidget.kt  # Status bar widget
    │   └── api/
    │       └── OrchestratorClient.kt     # HTTP client for Orchestrator API
    ├── src/main/resources/
    │   └── META-INF/plugin.xml           # Plugin descriptor
    └── build.gradle.kts
```

## Data Flow

```
[Developer IDE] --> [Extension/Plugin]
                         │
                         ├── GET /api/v1/releases/* ──────> [Orchestrator API]
                         ├── GET /api/v1/environments/* ──> [Orchestrator API]
                         ├── POST /api/v1/promotions/* ──-> [Orchestrator API]
                         └── POST /oauth/token ──────────-> [Authority]
```

1. **Authentication:** On activation, the extension initiates an OAuth device-code or browser-redirect flow against Authority. The obtained access token is stored in the IDE's secure credential store (VS Code `SecretStorage`, JetBrains `PasswordSafe`).
2. **Data retrieval:** Tree views and tool windows issue HTTP GET requests to the Orchestrator API on initial load and on manual/timed refresh.
3. **Actions:** Approve/reject/promote commands issue HTTP POST requests to the Orchestrator release control endpoints.
4. **Configuration validation:** The CodeLens provider (VS Code) and YAML annotator (JetBrains) parse `stella.yaml` files locally and highlight configuration issues inline.

## VS Code Extension Details

### Tree Views
- **Releases:** Hierarchical view of releases grouped by environment, showing status, version, and promotion eligibility
- **Environments:** Flat list of configured environments with health indicators

### CodeLens
- Inline annotations above `stella.yaml` entries showing the current deployment status of the referenced release
- Click-to-promote actions directly from the YAML file

### Status Bar
- Compact widget showing the number of pending promotions and overall platform health

### Webview Panels
- Detail panels for release timelines, evidence summaries, and deployment logs

## JetBrains Plugin Details

### Tool Windows
- **Releases tab:** Table view of all releases with sortable columns (version, environment, status, timestamp)
- **Environments tab:** Environment cards with health status and current deployments
- **Deployments tab:** Active and recent deployment history with log links

### YAML Annotator
- Real-time validation of `stella.yaml` files with gutter icons and tooltip messages for configuration issues

### Action Menus
- Context-sensitive actions (promote, approve, reject) available from tool window rows and editor context menus

## Security Considerations

- **Token storage:** OAuth tokens are stored exclusively in the IDE's built-in secure credential store; never persisted to disk in plaintext
- **Scope enforcement:** Extensions request only the scopes necessary for read operations and promotions (`release:read`, `release:promote`, `env:read`)
- **TLS enforcement:** All HTTP communication uses HTTPS; certificate validation is not bypassed
- **No secrets in configuration:** The `stella.yaml` file contains no credentials; integration secrets are managed by the Authority and Integrations modules

## Performance Characteristics

- Tree view refresh is debounced to avoid excessive API calls (default: 30-second minimum interval)
- API responses are cached locally with short TTL (60 seconds) to reduce latency on repeated navigation
- Webview panels and tool windows load data lazily on first open

## References

- [Module README](./README.md)
- [Orchestrator Architecture](../orchestrator/architecture.md)
- [Authority Architecture](../authority/architecture.md)