# yumankh/cipher architecture

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

- Interactive diagram: https://gitdiagram.com/yumankh/cipher
- Repository: https://github.com/yumankh/cipher

## Overview

Cipher is a zero-knowledge password manager: users authenticate and unlock a browser-held key, then manage encrypted passwords and notes. The client encrypts before sending ciphertext to the REST API; the API stores ciphertext and authentication material without receiving plaintext or the master password. Additional branches cover account/session management, vault organization, and informational/security pages. Edges are limited to relationships supported by excerpts, the source index, or the README; unsampled subsystem links are omitted.

Main entry points: [`frontend/src/lib/api.ts`](https://github.com/yumankh/cipher/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/pages/VaultPage.tsx`](https://github.com/yumankh/cipher/blob/main/frontend/src/pages/VaultPage.tsx) (Vault interface), [`frontend/src/pages/AuthPage.tsx`](https://github.com/yumankh/cipher/blob/main/frontend/src/pages/AuthPage.tsx) (Auth page), [`frontend/src/main.tsx`](https://github.com/yumankh/cipher/blob/main/frontend/src/main.tsx) (Application routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_auth_ui["Auth page<br/>[AuthPage.tsx]"]
  node_crypto["Client cryptography<br/>[crypto.ts]"]
  node_session["Session state<br/>[authStore.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_session_gate["Session gate<br/>[SessionGate.tsx]"]
  node_vault_page["Vault interface<br/>[VaultPage.tsx]"]
  node_vault_items["Vault item query<br/>[useVaultItems.ts]"]
  node_item_mutations["Item mutations"]
  node_settings["Account settings<br/>[SettingsPage.tsx]"]
  node_export["Vault export<br/>[exportVault.ts]"]
  node_public_pages["Public information"]
  node_router["Application routes<br/>[main.tsx]"]
end

subgraph group_api["REST API"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_auth_repo["Auth repository<br/>[auth.repository.ts]"]
  node_notes_controller["Notes controller"]
  node_notes_service["Notes service<br/>[notes.service.ts]"]
  node_notes_repo["Notes repository"]
  node_users_controller["Users controller"]
  node_users_service["Users service<br/>[users.service.ts]"]
  node_users_repo["Users repository"]
  node_auth_middleware["Auth middleware<br/>[requireAuth.ts]"]
  node_passwords_api["Password API"]
end

subgraph group_storage["Persistence"]
  node_db[("PostgreSQL data<br/>[prisma.ts]")]
end

node_user(("Vault user"))
node_api_actor(("REST API"))

node_user -->|"signs in"| node_auth_ui
node_auth_ui -->|"derives and wraps"| node_crypto
node_auth_ui -->|"submits auth"| node_api_client
node_auth_ui -->|"sets session"| node_session
node_router -->|"routes to"| node_auth_ui
node_router -->|"routes to"| node_vault_page
node_router -->|"routes to"| node_settings
node_router -->|"routes to"| node_public_pages
node_session_gate -->|"restores via"| node_api_client
node_session_gate -->|"updates state"| node_session
node_vault_page -->|"loads items"| node_vault_items
node_vault_page -->|"decrypts items"| node_crypto
node_vault_page -->|"uses mutations"| node_item_mutations
node_vault_items -->|"fetches items"| node_api_client
node_item_mutations -->|"sends changes"| node_api_client
node_item_mutations -->|"encrypts content"| node_crypto
node_api_client -->|"HTTP requests"| node_api_actor
node_api_actor -->|"auth endpoints"| node_auth_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"invokes"| node_auth_service
node_auth_service -->|"persists and reads"| node_auth_repo
node_auth_repo -->|"queries"| node_db
node_api_actor -->|"note requests"| node_notes_controller
node_notes_controller -->|"invokes"| node_notes_service
node_notes_service -->|"delegates"| node_notes_repo
node_notes_repo -->|"queries"| node_db
node_api_actor -->|"account requests"| node_users_controller
node_users_controller -->|"invokes"| node_users_service
node_users_service -->|"delegates"| node_users_repo
node_users_repo -->|"queries"| node_db
node_auth_middleware -.->|"guards requests"| node_api_actor
node_api_actor -.->|"password operations"| node_passwords_api
node_vault_page -.->|"exports vault"| node_export
node_settings -.->|"manages account"| node_api_client

click node_auth_ui "https://github.com/yumankh/cipher/blob/main/frontend/src/pages/AuthPage.tsx"
click node_crypto "https://github.com/yumankh/cipher/blob/main/frontend/src/lib/crypto.ts"
click node_session "https://github.com/yumankh/cipher/blob/main/frontend/src/stores/authStore.ts"
click node_api_client "https://github.com/yumankh/cipher/blob/main/frontend/src/lib/api.ts"
click node_session_gate "https://github.com/yumankh/cipher/blob/main/frontend/src/components/SessionGate.tsx"
click node_vault_page "https://github.com/yumankh/cipher/blob/main/frontend/src/pages/VaultPage.tsx"
click node_vault_items "https://github.com/yumankh/cipher/blob/main/frontend/src/hooks/useVaultItems.ts"
click node_item_mutations "https://github.com/yumankh/cipher/tree/main/frontend/src/hooks"
click node_settings "https://github.com/yumankh/cipher/blob/main/frontend/src/pages/SettingsPage.tsx"
click node_export "https://github.com/yumankh/cipher/blob/main/frontend/src/lib/exportVault.ts"
click node_public_pages "https://github.com/yumankh/cipher/tree/main/frontend/src/pages"
click node_router "https://github.com/yumankh/cipher/blob/main/frontend/src/main.tsx"
click node_auth_routes "https://github.com/yumankh/cipher/blob/main/backend/src/api/routes/auth.routes.ts"
click node_auth_controller "https://github.com/yumankh/cipher/blob/main/backend/src/api/controllers/auth.controller.ts"
click node_auth_service "https://github.com/yumankh/cipher/blob/main/backend/src/api/services/auth.service.ts"
click node_auth_repo "https://github.com/yumankh/cipher/blob/main/backend/src/api/repositories/auth.repository.ts"
click node_notes_controller "https://github.com/yumankh/cipher/blob/main/backend/src/api/controllers/notes.controller.ts"
click node_notes_service "https://github.com/yumankh/cipher/blob/main/backend/src/api/services/notes.service.ts"
click node_notes_repo "https://github.com/yumankh/cipher/blob/main/backend/src/api/repositories/notes.repository.ts"
click node_users_controller "https://github.com/yumankh/cipher/blob/main/backend/src/api/controllers/users.controller.ts"
click node_users_service "https://github.com/yumankh/cipher/blob/main/backend/src/api/services/users.service.ts"
click node_users_repo "https://github.com/yumankh/cipher/blob/main/backend/src/api/repositories/users.repository.ts"
click node_auth_middleware "https://github.com/yumankh/cipher/blob/main/backend/src/api/middlewares/requireAuth.ts"
click node_passwords_api "https://github.com/yumankh/cipher/tree/main/backend/src"
click node_db "https://github.com/yumankh/cipher/blob/main/backend/src/lib/prisma.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_auth_ui,node_crypto,node_session,node_api_client,node_session_gate,node_vault_page,node_vault_items,node_item_mutations,node_settings,node_export,node_public_pages,node_router,node_user toneBlue
class node_auth_routes,node_auth_controller,node_auth_service,node_auth_repo,node_notes_controller,node_notes_service,node_notes_repo,node_users_controller,node_users_service,node_users_repo,node_auth_middleware,node_passwords_api toneAmber
class node_db,node_api_actor toneMint
```

## Components

### Web client

- [Auth page](https://github.com/yumankh/cipher/blob/main/frontend/src/pages/AuthPage.tsx): `frontend/src/pages/AuthPage.tsx`
- [Client cryptography](https://github.com/yumankh/cipher/blob/main/frontend/src/lib/crypto.ts): `frontend/src/lib/crypto.ts`
- [Session state](https://github.com/yumankh/cipher/blob/main/frontend/src/stores/authStore.ts): `frontend/src/stores/authStore.ts`
- [API client](https://github.com/yumankh/cipher/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Session gate](https://github.com/yumankh/cipher/blob/main/frontend/src/components/SessionGate.tsx): `frontend/src/components/SessionGate.tsx`
- [Vault interface](https://github.com/yumankh/cipher/blob/main/frontend/src/pages/VaultPage.tsx): `frontend/src/pages/VaultPage.tsx`
- [Vault item query](https://github.com/yumankh/cipher/blob/main/frontend/src/hooks/useVaultItems.ts): `frontend/src/hooks/useVaultItems.ts`
- [Item mutations](https://github.com/yumankh/cipher/tree/main/frontend/src/hooks): `frontend/src/hooks`
- [Account settings](https://github.com/yumankh/cipher/blob/main/frontend/src/pages/SettingsPage.tsx): `frontend/src/pages/SettingsPage.tsx`
- [Vault export](https://github.com/yumankh/cipher/blob/main/frontend/src/lib/exportVault.ts): `frontend/src/lib/exportVault.ts`
- [Public information](https://github.com/yumankh/cipher/tree/main/frontend/src/pages): `frontend/src/pages`
- [Application routes](https://github.com/yumankh/cipher/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`

### REST API

- [Auth routes](https://github.com/yumankh/cipher/blob/main/backend/src/api/routes/auth.routes.ts): `backend/src/api/routes/auth.routes.ts`
- [Auth controller](https://github.com/yumankh/cipher/blob/main/backend/src/api/controllers/auth.controller.ts): `backend/src/api/controllers/auth.controller.ts`
- [Auth service](https://github.com/yumankh/cipher/blob/main/backend/src/api/services/auth.service.ts): `backend/src/api/services/auth.service.ts`
- [Auth repository](https://github.com/yumankh/cipher/blob/main/backend/src/api/repositories/auth.repository.ts): `backend/src/api/repositories/auth.repository.ts`
- [Notes controller](https://github.com/yumankh/cipher/blob/main/backend/src/api/controllers/notes.controller.ts): `backend/src/api/controllers/notes.controller.ts`
- [Notes service](https://github.com/yumankh/cipher/blob/main/backend/src/api/services/notes.service.ts): `backend/src/api/services/notes.service.ts`
- [Notes repository](https://github.com/yumankh/cipher/blob/main/backend/src/api/repositories/notes.repository.ts): `backend/src/api/repositories/notes.repository.ts`
- [Users controller](https://github.com/yumankh/cipher/blob/main/backend/src/api/controllers/users.controller.ts): `backend/src/api/controllers/users.controller.ts`
- [Users service](https://github.com/yumankh/cipher/blob/main/backend/src/api/services/users.service.ts): `backend/src/api/services/users.service.ts`
- [Users repository](https://github.com/yumankh/cipher/blob/main/backend/src/api/repositories/users.repository.ts): `backend/src/api/repositories/users.repository.ts`
- [Auth middleware](https://github.com/yumankh/cipher/blob/main/backend/src/api/middlewares/requireAuth.ts): `backend/src/api/middlewares/requireAuth.ts`
- [Password API](https://github.com/yumankh/cipher/tree/main/backend/src): `backend/src`

### Persistence

- [PostgreSQL data](https://github.com/yumankh/cipher/blob/main/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`

### Other components

- **Vault user**
- **REST API**

## Connections

- Vault user → Auth page: signs in
- Auth page → Client cryptography: derives and wraps (evidence: `frontend/src/pages/AuthPage.tsx`)
- Auth page → API client: submits auth (evidence: `frontend/src/pages/AuthPage.tsx`)
- Auth page → Session state: sets session (evidence: `frontend/src/pages/AuthPage.tsx`)
- Application routes → Auth page: routes to (evidence: `frontend/src/main.tsx`)
- Application routes → Vault interface: routes to (evidence: `frontend/src/main.tsx`)
- Application routes → Account settings: routes to (evidence: `frontend/src/main.tsx`)
- Application routes → Public information: routes to (evidence: `frontend/src/main.tsx`)
- Session gate → API client: restores via (evidence: `frontend/src/components/SessionGate.tsx`)
- Session gate → Session state: updates state (evidence: `frontend/src/components/SessionGate.tsx`)
- Vault interface → Vault item query: loads items (evidence: `frontend/src/pages/VaultPage.tsx`)
- Vault interface → Client cryptography: decrypts items (evidence: `frontend/src/pages/VaultPage.tsx`)
- Vault interface → Item mutations: uses mutations (evidence: `frontend/src/pages/VaultPage.tsx`)
- Vault item query → API client: fetches items (evidence: `frontend/src/hooks/useVaultItems.ts`)
- Item mutations → API client: sends changes (evidence: `frontend/src/hooks/useCreateItem.ts`)
- Item mutations → Client cryptography: encrypts content (evidence: `frontend/src/hooks/useCreateItem.ts`)
- API client → REST API: HTTP requests (evidence: `frontend/src/lib/api.ts`)
- REST API → Auth routes: auth endpoints
- Auth routes → Auth controller: dispatches (evidence: `backend/src/api/routes/auth.routes.ts`)
- Auth controller → Auth service: invokes (evidence: `backend/src/api/controllers/auth.controller.ts`)
- Auth service → Auth repository: persists and reads (evidence: `backend/src/api/services/auth.service.ts`)
- Auth repository → PostgreSQL data: queries (evidence: `backend/src/api/repositories/auth.repository.ts`)
- REST API → Notes controller: note requests
- Notes controller → Notes service: invokes (evidence: `backend/src/api/controllers/notes.controller.ts`)
- Notes service → Notes repository: delegates (evidence: `backend/src/api/services/notes.service.ts`)
- Notes repository → PostgreSQL data: queries (evidence: `backend/src/api/repositories/notes.repository.ts`)
- REST API → Users controller: account requests
- Users controller → Users service: invokes (evidence: `backend/src/api/controllers/users.controller.ts`)
- Users service → Users repository: delegates (evidence: `backend/src/api/services/users.service.ts`)
- Users repository → PostgreSQL data: queries (evidence: `backend/src/api/repositories/users.repository.ts`)
- Auth middleware → REST API: guards requests
- REST API → Password API: password operations
- Vault interface → Vault export: exports vault
- Account settings → API client: manages account
