# dotenvx/dotenvx architecture

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

- Interactive diagram: https://gitdiagram.com/dotenvx/dotenvx
- Repository: https://github.com/dotenvx/dotenvx

## Overview

dotenvx is a secure dotenv product: it encrypts secrets in .env files, distributes the encrypted files with code, and injects decrypted values when applications run. The primary workflow starts at the CLI `run` command, validates and resolves environment files, then launches the requested process with its environment; the README also documents encryption, key custody, commit protection, Armor, integrations, and SDK loading. Some implementation paths are represented at subsystem-directory level because their source was not sampled; edges are limited to README claims and relationships visible in indexed or excerpted files.

Main entry points: [`src/cli/actions/run.js`](https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/run.js) (Run action), [`src/cli/dotenvx.js`](https://github.com/dotenvx/dotenvx/blob/main/src/cli/dotenvx.js) (CLI commands), [`src/lib/main.js`](https://github.com/dotenvx/dotenvx/blob/main/src/lib/main.js) (SDK configuration), [`src/lib/services/validate.js`](https://github.com/dotenvx/dotenvx/blob/main/src/lib/services/validate.js) (Env validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["CLI commands<br/>[dotenvx.js]"]
  node_run["Run action<br/>[run.js]"]
  node_encrypt_action["Encrypt action<br/>[encrypt.js]"]
  node_protection["Commit protection<br/>[protect.js]"]
end

subgraph group_env["Environment processing"]
  node_sdk["SDK configuration<br/>[main.js]"]
  node_validation["Env validation<br/>[validate.js]"]
  node_envfiles["Envfile processing"]
  node_resolver["Environment resolution<br/>[envs.js]"]
  node_encrypt["Encryption transform<br/>[encrypt.js]"]
  node_decrypt["Decryption"]
  node_process["Command execution<br/>[executeCommand.js]"]
end

subgraph group_keys["Keys and custody"]
  node_key_storage["Key storage selection"]
  node_custodians["Custody providers"]
  node_session[("Session settings<br/>[session.js]")]
  node_device[("Device keys<br/>[device.js]")]
  node_armor["Armor operations"]
  node_integrations["External secret sources"]
end

subgraph group_services["Security and services"]
  node_armor_api["Armor API"]
  node_events["Event delivery"]
  node_redaction["Output redaction<br/>[redactOutput.js]"]
end

node_developer(("Developer"))
node_application(("Application process"))
node_git(("Git"))

node_developer -->|"invokes"| node_cli
node_cli -->|"routes command"| node_run
node_run -->|"validates inputs"| node_validation
node_validation -.->|"processes files"| node_envfiles
node_validation -.->|"resolves values"| node_resolver
node_run -.->|"launches command"| node_process
node_process -->|"injects environment"| node_application
node_developer -->|"encrypts secrets"| node_encrypt_action
node_cli -.->|"routes command"| node_encrypt_action
node_encrypt_action -.->|"encrypts values"| node_encrypt
node_application -->|"loads configuration"| node_sdk
node_sdk -->|"resolves envs"| node_resolver
node_sdk -.->|"decrypts values"| node_decrypt
node_developer -.->|"selects custody"| node_key_storage
node_key_storage -->|"queries choices"| node_custodians
node_custodians -.->|"uses device keys"| node_device
node_custodians -.->|"reads secrets"| node_integrations
node_developer -->|"protects commits"| node_protection
node_protection -.->|"guards commits"| node_git
node_developer -.->|"manages keys"| node_armor
node_armor -.->|"calls service"| node_armor_api
node_armor -->|"uses session"| node_session
node_run -->|"redacts output"| node_redaction
node_run -->|"emits events"| node_events

click node_cli "https://github.com/dotenvx/dotenvx/blob/main/src/cli/dotenvx.js"
click node_run "https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/run.js"
click node_encrypt_action "https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/encrypt.js"
click node_protection "https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/protect.js"
click node_sdk "https://github.com/dotenvx/dotenvx/blob/main/src/lib/main.js"
click node_validation "https://github.com/dotenvx/dotenvx/blob/main/src/lib/services/validate.js"
click node_envfiles "https://github.com/dotenvx/dotenvx/tree/main/src/lib/envfile"
click node_resolver "https://github.com/dotenvx/dotenvx/blob/main/src/lib/resolvers/envs.js"
click node_encrypt "https://github.com/dotenvx/dotenvx/blob/main/src/lib/transforms/encrypt.js"
click node_decrypt "https://github.com/dotenvx/dotenvx/tree/main/src/lib/decryptors"
click node_process "https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/executeCommand.js"
click node_key_storage "https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/selectKeyStorage.js"
click node_custodians "https://github.com/dotenvx/dotenvx/tree/main/src/lib/custodians"
click node_session "https://github.com/dotenvx/dotenvx/blob/main/src/db/session.js"
click node_device "https://github.com/dotenvx/dotenvx/blob/main/src/db/device.js"
click node_armor "https://github.com/dotenvx/dotenvx/tree/main/src/lib/services"
click node_armor_api "https://github.com/dotenvx/dotenvx/tree/main/src/lib/api"
click node_events "https://github.com/dotenvx/dotenvx/tree/main/src/lib/events"
click node_redaction "https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/redactOutput.js"
click node_integrations "https://github.com/dotenvx/dotenvx/tree/main/src/lib/custodians/local"

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_cli,node_run,node_encrypt_action,node_protection toneBlue
class node_sdk,node_validation,node_envfiles,node_resolver,node_encrypt,node_decrypt,node_process toneAmber
class node_key_storage,node_custodians,node_session,node_device,node_armor,node_integrations toneMint
class node_armor_api,node_events,node_redaction toneRose
class node_developer,node_application,node_git toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/dotenvx/dotenvx/blob/main/src/cli/dotenvx.js): `src/cli/dotenvx.js`
- [Run action](https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/run.js): `src/cli/actions/run.js`
- [Encrypt action](https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/encrypt.js): `src/cli/actions/encrypt.js`
- [Commit protection](https://github.com/dotenvx/dotenvx/blob/main/src/cli/actions/protect.js): `src/cli/actions/protect.js`

### Environment processing

- [SDK configuration](https://github.com/dotenvx/dotenvx/blob/main/src/lib/main.js): `src/lib/main.js`
- [Env validation](https://github.com/dotenvx/dotenvx/blob/main/src/lib/services/validate.js): `src/lib/services/validate.js`
- [Envfile processing](https://github.com/dotenvx/dotenvx/tree/main/src/lib/envfile): `src/lib/envfile`
- [Environment resolution](https://github.com/dotenvx/dotenvx/blob/main/src/lib/resolvers/envs.js): `src/lib/resolvers/envs.js`
- [Encryption transform](https://github.com/dotenvx/dotenvx/blob/main/src/lib/transforms/encrypt.js): `src/lib/transforms/encrypt.js`
- [Decryption](https://github.com/dotenvx/dotenvx/tree/main/src/lib/decryptors): `src/lib/decryptors`
- [Command execution](https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/executeCommand.js): `src/lib/helpers/executeCommand.js`

### Keys and custody

- [Key storage selection](https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/selectKeyStorage.js): `src/lib/helpers/selectKeyStorage.js`
- [Custody providers](https://github.com/dotenvx/dotenvx/tree/main/src/lib/custodians): `src/lib/custodians`
- [Session settings](https://github.com/dotenvx/dotenvx/blob/main/src/db/session.js): `src/db/session.js`
- [Device keys](https://github.com/dotenvx/dotenvx/blob/main/src/db/device.js): `src/db/device.js`
- [Armor operations](https://github.com/dotenvx/dotenvx/tree/main/src/lib/services): `src/lib/services`
- [External secret sources](https://github.com/dotenvx/dotenvx/tree/main/src/lib/custodians/local): `src/lib/custodians/local`

### Security and services

- [Armor API](https://github.com/dotenvx/dotenvx/tree/main/src/lib/api): `src/lib/api`
- [Event delivery](https://github.com/dotenvx/dotenvx/tree/main/src/lib/events): `src/lib/events`
- [Output redaction](https://github.com/dotenvx/dotenvx/blob/main/src/lib/helpers/redactOutput.js): `src/lib/helpers/redactOutput.js`

### Other components

- **Developer**
- **Application process**
- **Git**

## Connections

- Developer → CLI commands: invokes (evidence: `README.md`)
- CLI commands → Run action: routes command (evidence: `src/cli/dotenvx.js`)
- Run action → Env validation: validates inputs (evidence: `src/cli/actions/run.js`)
- Env validation → Envfile processing: processes files
- Env validation → Environment resolution: resolves values
- Run action → Command execution: launches command (evidence: `src/cli/actions/run.js`)
- Command execution → Application process: injects environment (evidence: `README.md`)
- Developer → Encrypt action: encrypts secrets (evidence: `README.md`)
- CLI commands → Encrypt action: routes command (evidence: `src/cli/dotenvx.js`)
- Encrypt action → Encryption transform: encrypts values
- Application process → SDK configuration: loads configuration (evidence: `README.md`)
- SDK configuration → Environment resolution: resolves envs (evidence: `src/lib/main.js`)
- SDK configuration → Decryption: decrypts values
- Developer → Key storage selection: selects custody
- Key storage selection → Custody providers: queries choices (evidence: `src/lib/helpers/selectKeyStorage.js`)
- Custody providers → Device keys: uses device keys
- Custody providers → External secret sources: reads secrets (evidence: `src/lib/custodians/index.js`)
- Developer → Commit protection: protects commits (evidence: `README.md`)
- Commit protection → Git: guards commits
- Developer → Armor operations: manages keys
- Armor operations → Armor API: calls service
- Armor operations → Session settings: uses session (evidence: `src/cli/actions/armor/move.js`)
- Run action → Output redaction: redacts output (evidence: `src/cli/actions/run.js`)
- Run action → Event delivery: emits events (evidence: `src/cli/actions/run.js`)
