# oracle/sql-developer-vscode architecture

> Architecture diagram of the GitHub repository oracle/sql-developer-vscode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oracle/sql-developer-vscode
- Repository: https://github.com/oracle/sql-developer-vscode

## Overview

This repository is not the SQL Developer application itself; it is a support repo for the Oracle SQL Developer Extension for VS Code. Its main purpose is to publish the extension API as an NPM package and provide example extensions that show how to use it.

1. Core product boundary  
The repo centers on the VS Code extension ecosystem. The public-facing contract is the Oracle SQL Developer extension API, while the actual database tooling lives in the separate Marketplace extension and Oracle documentation site.

2. Primary package: `extension-api`  
This is the main deliverable in the repo. It is an NPM package that exposes TypeScript declaration files (`dist/index.d.ts`) for the extension API. That means it defines the shape of the API without shipping a full runtime implementation in this repo.

3. API consumption model  
Downstream VS Code extensions or sample projects import these type definitions to build against the SQL Developer extension APIs in a type-safe way. The package acts as a compatibility layer and reference contract for extension authors.

4. Samples subsystem  
The `samples/` directory contains standalone VS Code extensions that demonstrate how to use the API. Architecturally, these are example consumers of `extension-api`, not part of the package itself. They help validate usage patterns and serve as reference integrations.

5. Build/publish flow  
The presence of `.github/workflows/npm-publish.yml` indicates an automated release path for publishing the `extension-api` package to NPM. The repo therefore has a lightweight CI/CD concern focused on packaging and distribution rather than running an application backend.

6. Repository layout and responsibilities  
- `extension-api/`: published package, type declarations, package metadata, changelog, and release/security docs  
- `samples/`: example VS Code extensions  
- root docs: repository-level guidance, contribution, security, and licensing  
This separation keeps the API contract isolated from examples and release automation.

7. Runtime and technology surface  
The relevant runtime here is the VS Code extension host, not a standalone server. The key technology is TypeScript type declarations packaged for NPM. The repo’s architecture is therefore client-side/extension-side, with no database, API server, or persistent service in this codebase.

8. External integration boundary  
The API ultimately targets Oracle Database workflows through the Oracle SQL Developer VS Code extension. The documentation link in the README points to Oracle-hosted product docs, which are the authoritative source for behavior and supported features.

9. Governance and release metadata  
`CHANGELOG.md`, `LICENSE.txt`, `SECURITY.md`, and `CONTRIBUTING.md` indicate this repo is managed as a distributable developer-facing package with formal release, legal, and vulnerability-disclosure processes.

10. Implication for an architecture diagram  
A good diagram would show:
- Oracle SQL Developer VS Code extension as the consumer of Oracle database features
- `extension-api` as the published TypeScript contract/package
- `samples` as reference consumer extensions
- NPM/GitHub Actions as the distribution path for the API package
- Oracle documentation/support as the external knowledge source  
There is no separate backend service in this repository’s architecture.

Main entry points: [`extension-api/package.json`](https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/package.json) (extension-api), [`README.md`](https://github.com/oracle/sql-developer-vscode/blob/main/README.md) (Repo docs), [`samples/.gitkeep`](https://github.com/oracle/sql-developer-vscode/blob/main/samples/.gitkeep) (Example usage), [`.github/workflows/npm-publish.yml`](https://github.com/oracle/sql-developer-vscode/blob/main/.github/workflows/npm-publish.yml) (Publish flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_readme["Repo docs<br/>guidance<br/>[README.md]"]
  node_governance["Governance<br/>policy docs"]
  node_publish_workflow["Publish flow<br/>GitHub Actions<br/>[npm-publish.yml]"]
  node_extension_api_pkg["extension-api<br/>npm package<br/>[package.json]"]
  node_api_types["API types<br/>TypeScript declarations<br/>[index.d.ts]"]
  node_api_readme["API docs<br/>package docs<br/>[README.md]"]
  node_api_changelog["Changelog<br/>release notes<br/>[CHANGELOG.md]"]
  node_api_security["API security<br/>package policy<br/>[SECURITY.md]"]
  node_samples_dir["Samples<br/>example extensions"]
  node_samples_example["Example usage<br/>sample extension<br/>[.gitkeep]"]
end

subgraph group_external["External"]
  node_vscode_host(("VS Code host<br/>runtime"))
  node_consumer_ext["Consumer extension<br/>downstream extension"]
  node_sql_developer_ext["SQL Developer<br/>Oracle extension"]
  node_npm_registry[("npm<br/>package registry")]
  node_oracle_docs["Oracle docs<br/>product docs"]
end

node_readme -->|"describes"| node_extension_api_pkg
node_readme -->|"contains"| node_samples_dir
node_readme -->|"references"| node_oracle_docs
node_governance -->|"governs"| node_extension_api_pkg
node_publish_workflow -->|"publishes"| node_extension_api_pkg
node_extension_api_pkg -->|"exports"| node_api_types
node_api_readme -->|"documents"| node_extension_api_pkg
node_api_changelog -->|"tracks"| node_extension_api_pkg
node_api_security -->|"secures"| node_extension_api_pkg
node_samples_dir -->|"contains"| node_samples_example
node_samples_example -->|"consumes"| node_extension_api_pkg
node_consumer_ext -->|"consumes"| node_extension_api_pkg
node_extension_api_pkg -->|"publishes to"| node_npm_registry
node_consumer_ext -->|"runs in"| node_vscode_host
node_sql_developer_ext -->|"runs in"| node_vscode_host
node_sql_developer_ext -->|"supported by"| node_oracle_docs
node_samples_example -->|"runs in"| node_vscode_host
node_publish_workflow -->|"delivers"| node_npm_registry

click node_readme "https://github.com/oracle/sql-developer-vscode/blob/main/README.md"
click node_publish_workflow "https://github.com/oracle/sql-developer-vscode/blob/main/.github/workflows/npm-publish.yml"
click node_extension_api_pkg "https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/package.json"
click node_api_types "https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/dist/index.d.ts"
click node_api_readme "https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/README.md"
click node_api_changelog "https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/CHANGELOG.md"
click node_api_security "https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/SECURITY.md"
click node_samples_example "https://github.com/oracle/sql-developer-vscode/blob/main/samples/.gitkeep"

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_readme,node_governance,node_publish_workflow,node_extension_api_pkg,node_api_types,node_api_readme,node_api_changelog,node_api_security,node_samples_dir,node_samples_example toneBlue
class node_vscode_host,node_consumer_ext,node_sql_developer_ext,node_npm_registry,node_oracle_docs toneAmber
```

## Components

### Repository

Files and packages maintained in this support repo

- [Repo docs](https://github.com/oracle/sql-developer-vscode/blob/main/README.md): guidance · Root repository guidance and policies · `README.md`
- **Governance**: policy docs · Contribution, security, and license documents
- [Publish flow](https://github.com/oracle/sql-developer-vscode/blob/main/.github/workflows/npm-publish.yml): GitHub Actions · Automated npm publishing pipeline · `.github/workflows/npm-publish.yml`
- [extension-api](https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/package.json): npm package · Published package that exposes the public extension contract · `extension-api/package.json`
- [API types](https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/dist/index.d.ts): TypeScript declarations · Distributed type definitions for the extension API · `extension-api/dist/index.d.ts`
- [API docs](https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/README.md): package docs · Package-level documentation and release notes · `extension-api/README.md`
- [Changelog](https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/CHANGELOG.md): release notes · Version history for the published API package · `extension-api/CHANGELOG.md`
- [API security](https://github.com/oracle/sql-developer-vscode/blob/main/extension-api/SECURITY.md): package policy · Security guidance for the extension-api package · `extension-api/SECURITY.md`
- **Samples**: example extensions · Standalone example VS Code extensions using the API
- [Example usage](https://github.com/oracle/sql-developer-vscode/blob/main/samples/.gitkeep): sample extension · Representative consumer showing how to use the API · `samples/.gitkeep`

### External

Consumers and services outside this repository

- **VS Code host**: runtime · Extension host runtime where downstream consumers execute
- **Consumer extension**: downstream extension · Third-party extension built against the published API
- **SQL Developer**: Oracle extension · Oracle SQL Developer extension for VS Code that consumes Oracle database features
- **npm**: package registry · Distribution target for the published extension-api package
- **Oracle docs**: product docs · External documentation and support source for the product and API behavior

## Connections

- Repo docs → extension-api: describes · Repository root points to the package as the main deliverable
- Repo docs → Samples: contains · Repository root includes example consumer extensions
- Repo docs → Oracle docs: references · Root documentation links to Oracle-hosted product guidance
- Governance → extension-api: governs · Repository policies apply to the published package
- Publish flow → extension-api: publishes · GitHub Actions workflow releases the package to npm
- extension-api → API types: exports · Package ships TypeScript declaration files
- API docs → extension-api: documents · Package README explains the contract and usage
- Changelog → extension-api: tracks · Version history for the API package
- API security → extension-api: secures · Package-specific vulnerability disclosure guidance
- Samples → Example usage: contains · Samples directory holds example extensions
- Example usage → extension-api: consumes · Example extensions build against the published API contract
- Consumer extension → extension-api: consumes · Downstream extensions import the API types
- extension-api → npm: publishes to · Package distribution target is the npm registry
- Consumer extension → VS Code host: runs in · Downstream extensions execute in the VS Code extension host
- SQL Developer → VS Code host: runs in · Oracle extension executes inside the VS Code extension host
- SQL Developer → Oracle docs: supported by · Oracle-hosted documentation is the authoritative behavior source
- Example usage → VS Code host: runs in · Samples are standalone VS Code extensions
- Publish flow → npm: delivers · Automated release path ends at npm
