aws / aws/graph-explorer

Retire the legacy configuration god-object in favor of explicit connection and schema models

Open
#1,839 0 comments 0 reactions 1 assignee Claimed by @kmcginnes View on GitHub
connection enhancement internal needs-triage schema tech debt
Dominant language
TypeScript
Stars
481
Forks
108
Avg merge
6d 8h
Merged PRs (30d)
5

Description

## Description

The connection/configuration layer is built around `RawConfiguration`, a legacy "god object" dating to the original 2022 port. It conflates three concerns that have since diverged:

- **Connection storage** — what a stored connection actually is: `{ id, displayLabel, connection }`.
- **Schema** — discovered/synced graph metadata, which is the source of truth in a *separate* atom (`schemaAtom`).
- **The exported-file envelope** — the on-disk format that bundles connection + schema together for portability.

`RawConfiguration` straddles all three. Most notably, it carries a `schema` field that **no released code path ever populates in memory** — import splits the exported file (connection → `configurationAtom`, schema → `schemaAtom`), schema sync writes only to `schemaAtom`, and create/default connections never set it. The result is dead merge logic, a type that overstates what it holds, and an export type that borrows the in-memory type (`Pick`), which is what keeps the dead field alive.

The key insight: **"a config has a schema" is true on disk but false in memory.** The code should make that split explicit rather than leaving one type spanning both.

## Motivation

- **Maintainability** — `mergeConfiguration` historically merged schema from three sources when only two were ever real, producing union-of-keys logic, an extra attribute-merge pass, and unknown-type fallbacks that existed solely to service the dead leg.
- **Honesty of the model** — a stored connection is `{ id, displayLabel, connection }`; the codebase already grew `ConnectionWithId` to cope with `RawConfiguration`'s awkwardness. The storage type should *be* that.
- **Upgrade safety is paramount** — these types are persisted to IndexedDB and exported to files in the wild. No change may cause an upgrading user to lose data or hit an error. Every slice must pin backward-compatible import and backup/restore behavior *before* refactoring (regression tests, per `.kiro/skills/testing/SKILL.md`).

## High-Level Plan

Tracer-bullet vertical slices, each independently shippable and behavior-preserving:

1. **Pin + remove the dead in-memory schema merge leg** — regression-test import-split and backup/restore, then drop the `currentConfig.schema` source from `mergeConfiguration`.
2. **Give the exported file its own type** — introduce an explicit `ExportedConnectionFile` type so the wire format no longer borrows the in-memory type; route its `schema` to `schemaAtom` as today.
3. **Remove `RawConfiguration.schema`** — once nothing reads it in memory.
4. **Migrate the storage type** — `configurationAtom: Map` → a connection record (reuse/extend `ConnectionWithId`), retiring `RawConfiguration`. ~20-file mechanical blast radius.

> [!IMPORTANT]
> Internal only — this issue is maintained by the core team and is not accepting external contributions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.