# etn-ecosystem/etn-identity-sdk architecture

> Architecture diagram of the GitHub repository etn-ecosystem/etn-identity-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/etn-ecosystem/etn-identity-sdk
- Repository: https://github.com/etn-ecosystem/etn-identity-sdk

## Overview

1. **Repository role**
   - This is a **published SDK package**, not an application.
   - Its job is to help a consuming app implement **“Sign in with ETN”** using the **OIDC Authorization Code Flow**.
   - The SDK’s scope is primarily **client-side initiation and UI**, while the README explicitly places **code exchange, session storage, and token rotation on the consumer’s backend**.

2. **Primary architectural boundary**
   - The key boundary is between:
     - **SDK code** in this repo
     - **Application backend/session layer** in the integrating app
     - **ETN Identity Provider** at `auth.etnecosystem.org`
   - The SDK initiates the login redirect, but **does not own the secure token/session lifecycle**.

3. **Source tree structure**
   - `src/` contains the authored TypeScript source.
   - `dist/` contains the compiled distributable artifacts (`.js` and `.d.ts`) that are published to npm.
   - This indicates a **library build pipeline**: author in TypeScript/React, compile to consumable JS plus type definitions.

4. **Public API surface**
   - `src/index.ts` is the likely **package entrypoint**, exporting the SDK’s supported surfaces.
   - `src/client.ts` contains the **programmatic auth client** used to construct ETN authorization URLs.
   - `src/components/ETNConnectButton.tsx` provides the **React UI component** for a login/connect action.

5. **Client-side auth flow**
   - The SDK’s client-side responsibility is to **build the authorization URL** and hand control to the browser via redirect.
   - It supports the standard OIDC login initiation pattern, including a **state value** for CSRF protection.
   - This makes the browser the start of the authentication flow, but not the place where secrets or tokens should be stored.

6. **UI component layer**
   - `ETNConnectButton` is the main reusable UI boundary.
   - It likely encapsulates the “sign in with ETN” interaction so consuming apps can add login with minimal wiring.
   - Architecturally, this is a thin presentation layer over the client auth helper.

7. **Distribution and typing**
   - `dist/client.js`, `dist/components/ETNConnectButton.js`, and corresponding `.d.ts` files show the package is shipped as **prebuilt runtime code plus TypeScript declarations**.
   - This matters for architecture because consumers do not compile the SDK source themselves; they integrate the published bundle.

8. **External dependency model**
   - The README documents the ETN Identity Provider endpoints, especially the token endpoint at `https://auth.etnecosystem.org/api/v1/oauth/token`.
   - The actual secure operations are performed by the **integrating app’s server**, which exchanges the auth code for tokens and manages refresh tokens.
   - The SDK therefore sits in front of an **external identity service**, but not in front of a proprietary backend.

9. **Session and token handling are intentionally outside the SDK**
   - The README shows session management using `iron-session`, but that code is presented as **integration guidance**, not as part of this repository’s source tree.
   - That means the repo is architected as a **frontend SDK plus documentation**, not a full auth platform.
   - If you diagram the full system, token rotation and session cookies should be shown in the consumer application, not inside this package.

10. **Docs and operational guidance**
   - `README.md` is a substantial architecture document in its own right, describing:
     - login redirect
     - callback handling
     - token exchange
     - session persistence
     - token rotation
   - `Integration-Debugging-Guide.md` suggests there is also operational guidance for troubleshooting integration issues, reinforcing that the repo is meant to support app developers adopting the ETN auth flow.

11. **Tooling/runtime**
   - The package is built with **TypeScript** and **npm**.
   - `tsconfig.json`, `package-lock.json`, and the compiled `dist/` output confirm a standard Node-based library workflow.
   - `public/` exists, but the tree does not show a full app shell; it likely contains assets used for documentation or examples rather than a live runtime backend.

12. **How to draw the architecture**
   - Place the **ETN Identity SDK** as a library box with two main exported surfaces:
     - a **client helper** for building login redirects
     - a **React connect button** for UI integration
   - Draw an arrow from the consuming browser app to **ETN Identity Provider** for authorization redirect.
   - Draw a separate arrow from the consumer’s backend to the **token endpoint** and session store, because that logic is outside the SDK but required for the overall authentication architecture.

Main entry points: [`src/client.ts`](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/client.ts) (Auth Client), [`src/index.ts`](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/index.ts) (Entry API), [`dist/index.js`](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/index.js) (Built API), [`src/components/ETNConnectButton.tsx`](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/components/ETNConnectButton.tsx) (Connect Button)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source"]
  node_src_index["Entry API<br/>ts entrypoint<br/>[index.ts]"]
  node_src_client["Auth Client<br/>oidc helper<br/>[client.ts]"]
  node_src_button["Connect Button<br/>react component"]
end

subgraph group_dist["Dist"]
  node_dist_index["Built API<br/>compiled entry<br/>[index.js]"]
  node_dist_client["Built Client<br/>compiled helper<br/>[client.js]"]
  node_dist_button["Built Button<br/>compiled component"]
  node_dist_types["Type Decls<br/>types<br/>[index.d.ts]"]
end

subgraph group_docs["Docs"]
  node_readme["README<br/>integration docs<br/>[README.md]"]
  node_debug_guide["Debug Guide<br/>ops docs"]
end

subgraph group_external["External"]
  node_browser_app["Consumer App<br/>host app"]
  node_app_backend["App Backend<br/>backend auth"]
  node_etn_idp(("ETN IdP<br/>oidc provider"))
  node_token_ep(("Token Endpoint<br/>oauth token api"))
  node_session_store[("Session Store<br/>session storage")]
end

node_repo["ETN SDK"]

node_repo -->|"exports"| node_src_index
node_repo -->|"publishes"| node_dist_index
node_src_index -->|"re-exports"| node_src_client
node_src_index -->|"re-exports"| node_src_button
node_src_client -->|"build redirect"| node_etn_idp
node_src_button -->|"uses"| node_src_client
node_dist_index -->|"bundles"| node_dist_client
node_dist_index -->|"bundles"| node_dist_button
node_browser_app -->|"renders"| node_src_button
node_browser_app -->|"initiates"| node_src_client
node_browser_app -->|"redirects to"| node_etn_idp
node_browser_app -->|"returns to"| node_app_backend
node_app_backend -->|"exchanges code"| node_token_ep
node_app_backend -->|"persists"| node_session_store
node_app_backend -->|"rotates tokens"| node_etn_idp
node_readme -.->|"documents"| node_app_backend
node_debug_guide -.->|"supports"| node_app_backend

click node_src_index "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/index.ts"
click node_src_client "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/client.ts"
click node_src_button "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/components/ETNConnectButton.tsx"
click node_dist_index "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/index.js"
click node_dist_client "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/client.js"
click node_dist_button "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/components/ETNConnectButton.js"
click node_dist_types "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/index.d.ts"
click node_readme "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/README.md"
click node_debug_guide "https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/Integration-Debugging-Guide.md"

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_src_index,node_src_client,node_src_button toneBlue
class node_dist_index,node_dist_client,node_dist_button,node_dist_types toneAmber
class node_readme,node_debug_guide toneMint
class node_browser_app,node_app_backend,node_etn_idp,node_token_ep,node_session_store toneRose
class node_repo toneNeutral
```

## Components

### Source

Authored TypeScript and React SDK code

- [Entry API](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/index.ts): ts entrypoint · Public exports for the SDK · `src/index.ts`
- [Auth Client](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/client.ts): oidc helper · Builds authorization URLs for login initiation · `src/client.ts`
- [Connect Button](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/src/components/ETNConnectButton.tsx): react component · UI component for sign-in or connect actions · `src/components/ETNConnectButton.tsx`

### Dist

Published JavaScript and type declarations

- [Built API](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/index.js): compiled entry · Published runtime and declaration entrypoint · `dist/index.js`
- [Built Client](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/client.js): compiled helper · Distributable auth helper implementation · `dist/client.js`
- [Built Button](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/components/ETNConnectButton.js): compiled component · Distributable connect button implementation · `dist/components/ETNConnectButton.js`
- [Type Decls](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/dist/index.d.ts): types · Published TypeScript declarations · `dist/index.d.ts`

### Docs

Integration and debugging guidance

- [README](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/README.md): integration docs · Explains the OIDC flow and backend responsibilities · `README.md`
- [Debug Guide](https://github.com/etn-ecosystem/etn-identity-sdk/blob/main/Integration-Debugging-Guide.md): ops docs · Troubleshooting guidance for integrations · `Integration-Debugging-Guide.md`

### External

Consumer app and ETN identity services

- **Consumer App**: host app · Integrating application using the SDK in the browser
- **App Backend**: backend auth · Handles code exchange, sessions, and token rotation
- **ETN IdP**: oidc provider · Authorization server at auth.etnecosystem.org
- **Token Endpoint**: oauth token api · Backend exchange endpoint for authorization code flow
- **Session Store**: session storage · Backend-managed session and token persistence

### Other components

- **ETN SDK**: library · Published package for initiating Sign in with ETN flows

## Connections

- ETN SDK → Entry API: exports · Package entrypoint exposes the supported SDK surface
- ETN SDK → Built API: publishes · Consumers install the compiled package artifacts
- Entry API → Auth Client: re-exports · Entry API surfaces the auth helper
- Entry API → Connect Button: re-exports · Entry API surfaces the UI component
- Auth Client → ETN IdP: build redirect · Constructs the authorization request sent to the identity provider
- Connect Button → Auth Client: uses · Button delegates login initiation to the auth helper
- Built API → Built Client: bundles · Compiled entry includes the helper surface
- Built API → Built Button: bundles · Compiled entry includes the component surface
- Consumer App → Connect Button: renders · Integrating app mounts the connect button in the UI
- Consumer App → Auth Client: initiates · Host app can programmatically start the auth redirect
- Consumer App → ETN IdP: redirects to · Browser is sent to ETN for authorization
- Consumer App → App Backend: returns to · Authorization callback lands in the integrating app
- App Backend → Token Endpoint: exchanges code · Backend swaps authorization code for tokens
- App Backend → Session Store: persists · Backend stores session state and rotation data
- App Backend → ETN IdP: rotates tokens · Backend may refresh tokens against the provider
- README → App Backend: documents · README explains the backend responsibilities outside the SDK
- Debug Guide → App Backend: supports · Debug guide helps troubleshoot integration issues