# jhaals/yopass architecture

> Architecture diagram of the GitHub repository jhaals/yopass, 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/jhaals/yopass
- Repository: https://github.com/jhaals/yopass

## Overview

1. **Overall shape**
   - Yopass is split into three main deliverables: a Go backend service, a React/TypeScript web app, and a separate Docusaurus-based microsite for docs/marketing. The core product is the backend plus web app; the microsite is mostly informational and licensing-related.

2. **Primary runtime: `yopass-server`**
   - `cmd/yopass-server` starts the production server. Its core logic lives in `pkg/server`, which owns HTTP handling, secret lifecycle, storage abstraction, authentication hooks, logging, metrics, and feature gating.

3. **Browser-side encryption is the core security boundary**
   - The web app encrypts secrets in the browser before upload. The server never sees plaintext secret content; it receives ciphertext and stores it until retrieval or expiration. This is the main trust boundary in the system.

4. **Secret creation and retrieval flow**
   - In `website/src/features/CreateSecret.tsx` and the display-secret flow, the client generates a key, encrypts the secret locally, and posts the encrypted payload to the server API.
   - Retrieval is one-time by default: the user opens a generated URL, the client fetches the ciphertext, decrypts locally, and the server removes or invalidates the stored record after access.

5. **Storage backends and expiry**
   - The backend is storage-agnostic for secret metadata and ciphertext, with Memcached as the default backend and Redis as an alternative. This is implemented through the database/storage layer in `pkg/server`.
   - File uploads are handled separately through file store abstractions (`disk`, `s3`, and DB-backed variants), with cleanup logic to enforce expiration and size limits.

6. **File sharing is a separate but related pipeline**
   - File uploads use streaming encryption/decryption paths, so large files do not need to be loaded fully into memory. The server mainly brokers encrypted file blobs and expiration metadata, while the client handles crypto.

7. **Feature modules in the backend**
   - `pkg/server` contains distinct subsystems for:
     - audit logging,
     - read receipts,
     - secret requests,
     - webhook delivery,
     - request/response handling,
     - OIDC authentication,
     - license verification and gated enterprise features.
   - These are layered on top of the core secret store rather than replacing it.

8. **Authentication and enterprise controls**
   - OIDC support lets deployments require login and restrict access by email domain. These features are integrated into the server, but are not mandatory for basic anonymous secret sharing.
   - Several advanced capabilities are license-gated, including theming/branding, audit logging, read receipts, and webhooks.

9. **Client application structure**
   - The `website` app is a modular SPA with feature folders for creating secrets, displaying secrets, request/reveal workflows, receipt lists, and read-only mode.
   - Shared code covers API access, crypto, auth state, configuration, localization, theming, and request/receipt persistence in the browser.

10. **Secondary CLI/library surface**
   - `pkg/yopass` and `cmd/yopass` provide a separate Go client/utility layer built on top of shared Yopass logic. This is distinct from the server and appears to support programmatic or command-line usage of the Yopass flows.

11. **Docs, microsite, and checkout flows**
   - The `microsite` directory is a separate frontend site for docs and public-facing pages. It also contains checkout/success/canceled routes, which suggests it participates in the licensing or purchase flow for paid features.
   - The repository’s `docs/` content and the microsite are not part of the secret-sharing runtime, but they are important for deployment, configuration, and feature discovery.

12. **Deployment topologies**
   - The repo supports multiple deployment modes: Docker, Docker Compose, Kubernetes, and AWS CDK.
   - The backend can run behind TLS itself or behind a reverse proxy; Memcached/Redis are external dependencies, and optional S3/MinIO or local disk can be used for file storage.

13. **Operational concerns**
   - The server includes logging, metrics, audit trails, and cleanup routines, so the architecture is not just request/response API serving; it also has background expiration and compliance-oriented event recording.
   - Webhooks provide outbound notifications for secret lifecycle events, extending the system beyond its own storage boundary.

14. **Key diagram boundary**
   - The most important architectural diagram should show: browser/client encryption and UI on one side, the Go server as the trust-minimized API in the middle, and storage/auth/notification backends as external dependencies on the other side.

Main entry points: [`pkg/server/server.go`](https://github.com/jhaals/yopass/blob/master/pkg/server/server.go) (Server core), [`website/src/app/App.tsx`](https://github.com/jhaals/yopass/blob/master/website/src/app/App.tsx) (SPA shell), [`website/src/shared/lib/crypto.ts`](https://github.com/jhaals/yopass/blob/master/website/src/shared/lib/crypto.ts) (Browser crypto), [`website/src/shared/lib/api.ts`](https://github.com/jhaals/yopass/blob/master/website/src/shared/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core runtime"]
  node_cmd_yopass_server["Server entry<br/>go main<br/>[main.go]"]
  node_server_core["Server core<br/>http service<br/>[server.go]"]
  node_server_db[("Secret store<br/>storage layer<br/>[database.go]")]
  node_server_filestore[("File store<br/>blob storage<br/>[filestore.go]")]
  node_server_cleanup["Cleanup job<br/>expiry worker"]
  node_server_oidc["OIDC auth<br/>auth hook<br/>[oidc.go]"]
  node_server_license["License gate<br/>feature gating<br/>[license.go]"]
  node_server_audit["Audit log<br/>compliance<br/>[audit.go]"]
  node_server_webhook["Webhooks<br/>notifications<br/>[webhook.go]"]
  node_server_stream["Streaming path<br/>file crypto<br/>[server_stream.go]"]
  node_pkg_yopass["Yopass lib<br/>go client lib<br/>[yopass.go]"]
  node_cmd_yopass["CLI entry<br/>go cli<br/>[main.go]"]
end

subgraph group_webapp["Web app"]
  node_website_app["SPA shell<br/>react app<br/>[App.tsx]"]
  node_web_crypto["Browser crypto<br/>client crypto<br/>[crypto.ts]"]
  node_web_api["API client<br/>frontend api<br/>[api.ts]"]
  node_create_secret["Create secret<br/>feature<br/>[CreateSecret.tsx]"]
  node_decrypt_secret["Decrypt secret<br/>feature<br/>[Decryptor.tsx]"]
  node_stream_upload["Streaming upload<br/>feature"]
  node_request_secret["Secret requests<br/>feature<br/>[CreateRequest.tsx]"]
  node_auth_state["Auth state<br/>frontend auth<br/>[AuthProvider.tsx]"]
end

subgraph group_site["Microsite"]
  node_microsite_home["Docs site<br/>docusaurus site<br/>[index.tsx]"]
  node_checkout_flow["Checkout<br/>purchase flow<br/>[CheckoutModal.tsx]"]
end

subgraph group_deploy["Deployment"]
  node_cdk_stack["CDK stack<br/>infra stack<br/>[cdk-stack.ts]"]
end

node_cmd_yopass_server -->|"starts"| node_server_core
node_server_core -->|"stores"| node_server_db
node_server_core -->|"brokers files"| node_server_filestore
node_server_core -->|"streams"| node_server_stream
node_server_core -->|"auth"| node_server_oidc
node_server_core -->|"gates"| node_server_license
node_server_core -->|"logs"| node_server_audit
node_server_core -->|"notifies"| node_server_webhook
node_server_filestore -->|"expires"| node_server_cleanup
node_website_app -->|"routes"| node_create_secret
node_website_app -->|"routes"| node_decrypt_secret
node_website_app -->|"routes"| node_stream_upload
node_website_app -->|"routes"| node_request_secret
node_website_app -->|"state"| node_auth_state
node_create_secret -->|"encrypts"| node_web_crypto
node_create_secret -->|"uploads"| node_web_api
node_decrypt_secret -->|"fetches"| node_web_api
node_decrypt_secret -->|"decrypts"| node_web_crypto
node_stream_upload -->|"encrypts"| node_web_crypto
node_stream_upload -->|"uploads"| node_web_api
node_request_secret -->|"syncs"| node_web_api
node_pkg_yopass -.->|"shares logic"| node_web_crypto
node_cmd_yopass -->|"uses"| node_pkg_yopass
node_microsite_home -->|"links"| node_checkout_flow
node_cdk_stack -->|"deploys"| node_server_core
node_cdk_stack -->|"deploys"| node_website_app

click node_cmd_yopass_server "https://github.com/jhaals/yopass/blob/master/cmd/yopass-server/main.go"
click node_server_core "https://github.com/jhaals/yopass/blob/master/pkg/server/server.go"
click node_server_db "https://github.com/jhaals/yopass/blob/master/pkg/server/database.go"
click node_server_filestore "https://github.com/jhaals/yopass/blob/master/pkg/server/filestore.go"
click node_server_cleanup "https://github.com/jhaals/yopass/blob/master/pkg/server/filestore_cleanup.go"
click node_server_oidc "https://github.com/jhaals/yopass/blob/master/pkg/server/oidc.go"
click node_server_license "https://github.com/jhaals/yopass/blob/master/pkg/server/license.go"
click node_server_audit "https://github.com/jhaals/yopass/blob/master/pkg/server/audit.go"
click node_server_webhook "https://github.com/jhaals/yopass/blob/master/pkg/server/webhook.go"
click node_server_stream "https://github.com/jhaals/yopass/blob/master/pkg/server/server_stream.go"
click node_pkg_yopass "https://github.com/jhaals/yopass/blob/master/pkg/yopass/yopass.go"
click node_cmd_yopass "https://github.com/jhaals/yopass/blob/master/cmd/yopass/main.go"
click node_website_app "https://github.com/jhaals/yopass/blob/master/website/src/app/App.tsx"
click node_web_crypto "https://github.com/jhaals/yopass/blob/master/website/src/shared/lib/crypto.ts"
click node_web_api "https://github.com/jhaals/yopass/blob/master/website/src/shared/lib/api.ts"
click node_create_secret "https://github.com/jhaals/yopass/blob/master/website/src/features/CreateSecret.tsx"
click node_decrypt_secret "https://github.com/jhaals/yopass/blob/master/website/src/features/display-secret/Decryptor.tsx"
click node_stream_upload "https://github.com/jhaals/yopass/blob/master/website/src/features/StreamingUpload.tsx"
click node_request_secret "https://github.com/jhaals/yopass/blob/master/website/src/features/request-secret/CreateRequest.tsx"
click node_auth_state "https://github.com/jhaals/yopass/blob/master/website/src/shared/context/AuthProvider.tsx"
click node_microsite_home "https://github.com/jhaals/yopass/blob/master/microsite/src/pages/index.tsx"
click node_checkout_flow "https://github.com/jhaals/yopass/blob/master/microsite/src/components/CheckoutModal.tsx"
click node_cdk_stack "https://github.com/jhaals/yopass/blob/master/deploy/cdk/lib/cdk-stack.ts"

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_cmd_yopass_server,node_server_core,node_server_db,node_server_filestore,node_server_cleanup,node_server_oidc,node_server_license,node_server_audit,node_server_webhook,node_server_stream,node_pkg_yopass,node_cmd_yopass toneBlue
class node_website_app,node_web_crypto,node_web_api,node_create_secret,node_decrypt_secret,node_stream_upload,node_request_secret,node_auth_state toneAmber
class node_microsite_home,node_checkout_flow toneMint
class node_cdk_stack toneRose
```

## Components

### Core runtime

Go server and CLI surfaces that implement secret storage and retrieval.

- [Server entry](https://github.com/jhaals/yopass/blob/master/cmd/yopass-server/main.go): go main · Starts the production server process. · `cmd/yopass-server/main.go`
- [Server core](https://github.com/jhaals/yopass/blob/master/pkg/server/server.go): http service · Owns request handling, feature wiring, and secret lifecycle orchestration. · `pkg/server/server.go`
- [Secret store](https://github.com/jhaals/yopass/blob/master/pkg/server/database.go): storage layer · Abstracts metadata and ciphertext persistence across backends. · `pkg/server/database.go`
- [File store](https://github.com/jhaals/yopass/blob/master/pkg/server/filestore.go): blob storage · Manages encrypted file blobs and storage backends. · `pkg/server/filestore.go`
- [Cleanup job](https://github.com/jhaals/yopass/blob/master/pkg/server/filestore_cleanup.go): expiry worker · Enforces expiration, size limits, and file cleanup. · `pkg/server/filestore_cleanup.go`
- [OIDC auth](https://github.com/jhaals/yopass/blob/master/pkg/server/oidc.go): auth hook · Adds login and domain-based access control. · `pkg/server/oidc.go`
- [License gate](https://github.com/jhaals/yopass/blob/master/pkg/server/license.go): feature gating · Verifies license state and enables enterprise features. · `pkg/server/license.go`
- [Audit log](https://github.com/jhaals/yopass/blob/master/pkg/server/audit.go): compliance · Records security and lifecycle events. · `pkg/server/audit.go`
- [Webhooks](https://github.com/jhaals/yopass/blob/master/pkg/server/webhook.go): notifications · Delivers outbound events for secret lifecycle changes. · `pkg/server/webhook.go`
- [Streaming path](https://github.com/jhaals/yopass/blob/master/pkg/server/server_stream.go): file crypto · Handles streaming upload and download flows for large files. · `pkg/server/server_stream.go`
- [Yopass lib](https://github.com/jhaals/yopass/blob/master/pkg/yopass/yopass.go): go client lib · Shared client-side Go library for Yopass flows. · `pkg/yopass/yopass.go`
- [CLI entry](https://github.com/jhaals/yopass/blob/master/cmd/yopass/main.go): go cli · Command-line utility built on the shared Yopass library. · `cmd/yopass/main.go`

### Web app

Browser application for secret creation, retrieval, receipts, and requests.

- [SPA shell](https://github.com/jhaals/yopass/blob/master/website/src/app/App.tsx): react app · Top-level browser application and routing container. · `website/src/app/App.tsx`
- [Browser crypto](https://github.com/jhaals/yopass/blob/master/website/src/shared/lib/crypto.ts): client crypto · Encrypts and decrypts secrets locally before and after transfer. · `website/src/shared/lib/crypto.ts`
- [API client](https://github.com/jhaals/yopass/blob/master/website/src/shared/lib/api.ts): frontend api · Encapsulates calls to the backend service. · `website/src/shared/lib/api.ts`
- [Create secret](https://github.com/jhaals/yopass/blob/master/website/src/features/CreateSecret.tsx): feature · Generates keys, encrypts payloads, and submits ciphertext. · `website/src/features/CreateSecret.tsx`
- [Decrypt secret](https://github.com/jhaals/yopass/blob/master/website/src/features/display-secret/Decryptor.tsx): feature · Fetches ciphertext and decrypts it locally in the browser. · `website/src/features/display-secret/Decryptor.tsx`
- [Streaming upload](https://github.com/jhaals/yopass/blob/master/website/src/features/StreamingUpload.tsx): feature · Browser-side upload flow for large encrypted files. · `website/src/features/StreamingUpload.tsx`
- [Secret requests](https://github.com/jhaals/yopass/blob/master/website/src/features/request-secret/CreateRequest.tsx): feature · Creates and manages request/reveal workflows. · `website/src/features/request-secret/CreateRequest.tsx`
- [Auth state](https://github.com/jhaals/yopass/blob/master/website/src/shared/context/AuthProvider.tsx): frontend auth · Tracks login requirements and access state in the UI. · `website/src/shared/context/AuthProvider.tsx`

### Microsite

Docs, public pages, and licensing checkout flows.

- [Docs site](https://github.com/jhaals/yopass/blob/master/microsite/src/pages/index.tsx): docusaurus site · Public-facing pages, documentation, and marketing content. · `microsite/src/pages/index.tsx`
- [Checkout](https://github.com/jhaals/yopass/blob/master/microsite/src/components/CheckoutModal.tsx): purchase flow · Licensing and purchase success/cancel routes. · `microsite/src/components/CheckoutModal.tsx`

### Deployment

Packaging and infrastructure entry points.

- [CDK stack](https://github.com/jhaals/yopass/blob/master/deploy/cdk/lib/cdk-stack.ts): infra stack · Infrastructure deployment definition for cloud setups. · `deploy/cdk/lib/cdk-stack.ts`

## Connections

- Server entry → Server core: starts · Bootstraps the HTTP service and configuration.
- Server core → Secret store: stores · Persists ciphertext and secret metadata.
- Server core → File store: brokers files · Routes file-backed secrets to the blob layer.
- Server core → Streaming path: streams · Handles large encrypted file transfer.
- Server core → OIDC auth: auth · Optionally requires login and domain checks.
- Server core → License gate: gates · Enables enterprise-only capabilities.
- Server core → Audit log: logs · Emits audit events for security-sensitive actions.
- Server core → Webhooks: notifies · Sends lifecycle events outward.
- File store → Cleanup job: expires · Cleans up expired files and enforces limits.
- SPA shell → Create secret: routes · Shows the secret creation flow.
- SPA shell → Decrypt secret: routes · Shows the retrieval and decrypt flow.
- SPA shell → Streaming upload: routes · Shows the large-file upload flow.
- SPA shell → Secret requests: routes · Shows request and reveal workflows.
- SPA shell → Auth state: state · Propagates login and read-only status.
- Create secret → Browser crypto: encrypts · Creates keys and ciphertext in the browser.
- Create secret → API client: uploads · Posts encrypted payloads to the server.
- Decrypt secret → API client: fetches · Retrieves ciphertext or file blobs.
- Decrypt secret → Browser crypto: decrypts · Recovers plaintext locally.
- Streaming upload → Browser crypto: encrypts · Streams encrypted file content from the browser.
- Streaming upload → API client: uploads · Sends encrypted file chunks and metadata.
- Secret requests → API client: syncs · Creates requests and updates reveal state.
- Yopass lib → Browser crypto: shares logic · Reuses common Yopass flow primitives.
- CLI entry → Yopass lib: uses · Builds CLI behavior on the shared library.
- Docs site → Checkout: links · Connects docs and marketing pages to licensing flows.
- CDK stack → Server core: deploys · Defines cloud deployment for the backend runtime.
- CDK stack → SPA shell: deploys · Can package the web application as part of infrastructure.