Add architecture documentation and fix inaccuracies

docs/README.md

@@ -5,3 +5,4 @@
 - [Guides](./guides) — Connect to databases, deploy to AWS, and troubleshoot common issues.
 - [References](./references) — Security, logging, health checks, and configuration details.
 - [Development](./development.md) — Build from source and contribute to Graph Explorer.
+- [Architecture](./architecture.md) — System design, key libraries, and the connector pattern.

docs/architecture.md

@@ -0,0 +1,46 @@
+# Architecture
+
+Graph Explorer is a client-heavy web application with a thin backend proxy. The browser does most of the work — constructing queries, managing state, and rendering the graph — while the server handles request forwarding and signing.
+
+## Supported Graph Data Models and Query Languages
+
+- Labelled Property Graph (PG) using Gremlin or openCypher
+- Resource Description Framework (RDF) using SPARQL
+
+## System Overview
+
+```mermaid
+graph LR
+    Browser["Browser\n(React)"] -- HTTP --> Proxy["Proxy Server\n(Express)"]
+    Proxy -- HTTP --> DB["Graph Database\n(Neptune, etc.)"]
+    Browser -. direct .-> DB
+    Browser -- persistence --> IDB["IndexedDB\n(localforage)"]
+```
+
+The React client constructs queries and sends them through the proxy server, which forwards requests to the graph database. When connecting to Amazon Neptune, the proxy signs requests with AWS SigV4 credentials. For non-Neptune databases, the proxy is optional — the client can connect directly to a publicly accessible endpoint (shown as the dotted line above).
+
+The proxy does not store any user data — all preferences, connections, and query history live in the browser's IndexedDB.
+
+This split exists because browsers cannot perform SigV4 signing directly (it requires AWS credentials that should not be exposed to the client), and because the proxy can run inside a VPC alongside the database while the browser runs outside it.
+
+## Monorepo Structure
+
+The repository uses pnpm workspaces with two main packages:
+
+- **`packages/graph-explorer`** — The React client. Contains all UI components, state management, and database query logic.
+- **`packages/graph-explorer-proxy-server`** — The Express server. Handles request proxying, SigV4 signing, HTTPS termination, and serving the built client assets.
+
+## Key Libraries
+
+| Library                                                   | Role                | Why                                                                           |
+| --------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- |
+| [Cytoscape.js](https://js.cytoscape.org/)                 | Graph rendering     | Mature canvas-based graph library with layout plugins and interaction support |
+| [Jotai](https://jotai.org/)                               | Client state        | Atom-based model that avoids unnecessary re-renders in a component-heavy UI   |
+| [TanStack Query](https://tanstack.com/query)              | Remote data caching | Handles caching, deduplication, and background refresh for database queries   |
+| [localforage](https://localforage.github.io/localForage/) | Persistence         | Provides an async IndexedDB API for storing user data client-side             |
+
+## Connector & Explorer Pattern
+
+Graph Explorer supports three query languages (Gremlin, openCypher, SPARQL) through a connector abstraction. Each query language has an "explorer" that implements a common interface for operations like searching nodes, fetching neighbors, and discovering schema.
+
+The UI code calls the explorer interface without knowing which query language is active. The active connection's query language determines which explorer handles the request. This keeps query-language-specific logic isolated from the rest of the application.

docs/development.md

@@ -1,6 +1,6 @@
 # Development
 
-This developer README details instructions for building on top of the graph-explorer application, or for configuring advanced settings, like using environment variables to switch to HTTP.
+Build instructions and development setup for contributing to Graph Explorer. For system design and key libraries, see [Architecture](./architecture.md).
 
 ## Requirements
 
@@ -27,11 +27,6 @@ corepack enable
 
 If `corepack` is not found, install it first with `npm install -g corepack@latest`.
 
-## Supported Graph Data Models and Query Languages
-
-- Labelled Property Graph (PG) using Gremlin or openCypher
-- Resource Description Framework (RDF) using SPARQL
-
 ## Run in development mode
 
 Install any missing or updated dependencies.
@@ -56,21 +51,14 @@ At this point, Graph Explorer should be successfully running and it is asking yo
 
 ## Build for production
 
-Building Graph Explorer is simple.
-
 ```bash
 pnpm install
 pnpm build
 ```
 
-This will run the build across the both the client code and the proxy server code. You'll end up with two `dist` folders:
-
-```
-{ROOT_PATH}/packages/graph-explorer/dist/
-{ROOT_PATH}/packages/graph-explorer-proxy-server/dist/
-```
+This builds the React client into static assets at `packages/graph-explorer/dist/`. The proxy server has no build step — Node runs its TypeScript source directly using [native type stripping](https://nodejs.org/en/learn/typescript/run-natively#native-type-stripping).
 
-The recommended way to serve Graph Explorer is using the proxy server.
+Start the proxy server, which also serves the built client assets:
 
 ```bash
 pnpm start

docs/guides/deploy-with-docker.md

@@ -50,4 +50,4 @@ You can find the latest version of the image on
    ```
 
 5. You will receive a warning as the SSL certificate used is self-signed. Since the application is set to use HTTPS by default and contains a self-signed certificate, you will need to add the Graph Explorer certificates to the trusted certificates directory and manually trust them. See the [HTTPS Connections](./troubleshooting.md#https-connections) section.
-6. After completing the trusted certification step and refreshing the browser, you should now see the Connections UI. See below description on Connections UI to configure your first connection to Amazon Neptune.
+6. After completing the trusted certification step and refreshing the browser, you should now see the Connections UI. See [Connections](../features/connections.md) for details on configuring your first connection.