stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

consolidation of some of the modules, localization fixes, product advisories work, qa work

Browse Source
This commit is contained in:
master
2026-03-05 03:54:22 +02:00
parent 7bafcc3eef
commit 8e1cb9448d
3878 changed files with 72600 additions and 46861 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
docs-archived/modules/extensions/architecture.md Normal file
View File

@@ -0,0 +1,117 @@
# 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)