# aktdx/vaultkey architecture

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

- Interactive diagram: https://gitdiagram.com/aktdx/vaultkey
- Repository: https://github.com/aktdx/vaultkey

## Overview

VaultKey is a privacy-focused file-sharing application: the browser encrypts files before upload, owners configure and manage share links, and recipients obtain ciphertext through server-enforced access checks before decrypting locally. The graph includes the documented upload, access-control, revocation, and audit capabilities. Backend route internals and several frontend pages were not sampled, so links between those components follow documented behavior and are kept at the subsystem level.

Main entry points: [`frontend/src/lib/api.ts`](https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/api.ts) (API client), [`backend/app/main.py`](https://github.com/aktdx/vaultkey/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/database.py`](https://github.com/aktdx/vaultkey/blob/main/backend/app/database.py) (Relational database), [`frontend/src/pages/SecureDownloadPage.tsx`](https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/SecureDownloadPage.tsx) (Secure download)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser application"]
  node_app["Route application<br/>[App.tsx]"]
  node_authpages["Sign-in pages<br/>[AuthPages.tsx]"]
end

subgraph group_identity["Identity and sessions"]
  node_authctx["Auth context<br/>[AuthContext.tsx]"]
  node_firebaseclient["Firebase client<br/>[firebase.ts]"]
  node_firebaseverify["Firebase verification"]
end

subgraph group_sharing["File sharing"]
  node_filesui["File management<br/>[FilesPage.tsx]"]
  node_uploadui["File upload<br/>[FileUpload.tsx]"]
  node_crypt["Browser cryptography<br/>[crypto.ts]"]
  node_shareui["Share management<br/>[SharesPage.tsx]"]
  node_createui["Create share"]
  node_downloadui["Secure download"]
  node_viewer["View-only viewer<br/>[ViewOnlyViewer.tsx]"]
  node_activityui["Activity timeline<br/>[ActivityPage.tsx]"]
end

subgraph group_backend["API and policy"]
  node_api["API client<br/>[api.ts]"]
  node_main["FastAPI application<br/>[main.py]"]
  node_authroute["Authentication routes<br/>[auth.py]"]
  node_fileroute["File routes<br/>[files.py]"]
  node_shareroute["Share routes<br/>[shares.py]"]
  node_accessroute["Access routes<br/>[access.py]"]
  node_activityroute["Activity routes<br/>[activity.py]"]
  node_security["Token security<br/>[security.py]"]
end

subgraph group_state["Persistence and storage"]
  node_database[("Relational database<br/>[database.py]")]
  node_storage["Object storage adapter<br/>[storage.py]"]
end

node_owner(("File owner"))
node_recipient(("Link recipient"))
node_google["Firebase Auth"]
node_postgres[("Neon PostgreSQL")]
node_r2[("Cloudflare R2")]

node_owner -->|"signs in"| node_authpages
node_authpages -->|"calls"| node_authctx
node_authctx -->|"auth requests"| node_api
node_authctx -->|"starts Google sign-in"| node_firebaseclient
node_firebaseclient -.->|"authenticates"| node_google
node_authctx -->|"exchanges ID token"| node_api
node_app -->|"routes"| node_filesui
node_app -->|"routes"| node_shareui
node_app -->|"routes"| node_downloadui
node_app -->|"routes"| node_activityui
node_owner -->|"selects file"| node_uploadui
node_uploadui -->|"encrypts locally"| node_crypt
node_uploadui -->|"uploads ciphertext"| node_api
node_owner -->|"sets controls"| node_createui
node_createui -->|"creates share"| node_api
node_shareui -->|"manages shares"| node_api
node_recipient -->|"opens link"| node_downloadui
node_downloadui -->|"requests access"| node_api
node_downloadui -->|"decrypts locally"| node_crypt
node_downloadui -->|"presents content"| node_viewer
node_activityui -->|"loads events"| node_api
node_api -->|"sends requests"| node_main
node_main -->|"dispatches"| node_authroute
node_main -->|"dispatches"| node_fileroute
node_main -->|"dispatches"| node_shareroute
node_main -->|"dispatches"| node_accessroute
node_main -->|"dispatches"| node_activityroute
node_authroute -->|"issues tokens"| node_security
node_authroute -->|"verifies Google token"| node_firebaseverify
node_authroute -->|"reads and writes users"| node_database
node_fileroute -->|"stores ciphertext"| node_storage
node_fileroute -->|"records file metadata"| node_database
node_shareroute -->|"stores share controls"| node_database
node_accessroute -->|"checks limits and logs"| node_database
node_accessroute -->|"streams ciphertext"| node_storage
node_activityroute -->|"reads activity"| node_database
node_database -->|"queries"| node_postgres
node_storage -->|"stores and streams objects"| node_r2

click node_app "https://github.com/aktdx/vaultkey/blob/main/frontend/src/App.tsx"
click node_authpages "https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/auth/AuthPages.tsx"
click node_authctx "https://github.com/aktdx/vaultkey/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_firebaseclient "https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/firebase.ts"
click node_api "https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/api.ts"
click node_filesui "https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/dashboard/FilesPage.tsx"
click node_uploadui "https://github.com/aktdx/vaultkey/blob/main/frontend/src/components/upload/FileUpload.tsx"
click node_crypt "https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/crypto.ts"
click node_shareui "https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/dashboard/SharesPage.tsx"
click node_createui "https://github.com/aktdx/vaultkey/blob/main/frontend/src/components/shares/CreateShareModal.tsx"
click node_downloadui "https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/SecureDownloadPage.tsx"
click node_viewer "https://github.com/aktdx/vaultkey/blob/main/frontend/src/components/shares/ViewOnlyViewer.tsx"
click node_activityui "https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/dashboard/ActivityPage.tsx"
click node_main "https://github.com/aktdx/vaultkey/blob/main/backend/app/main.py"
click node_authroute "https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/auth.py"
click node_fileroute "https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/files.py"
click node_shareroute "https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/shares.py"
click node_accessroute "https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/access.py"
click node_activityroute "https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/activity.py"
click node_security "https://github.com/aktdx/vaultkey/blob/main/backend/app/security.py"
click node_firebaseverify "https://github.com/aktdx/vaultkey/blob/main/backend/app/firebase_service.py"
click node_database "https://github.com/aktdx/vaultkey/blob/main/backend/app/database.py"
click node_storage "https://github.com/aktdx/vaultkey/blob/main/backend/app/storage.py"

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_app,node_authpages toneBlue
class node_authctx,node_firebaseclient,node_firebaseverify,node_postgres,node_r2 toneAmber
class node_filesui,node_uploadui,node_crypt,node_shareui,node_createui,node_downloadui,node_viewer,node_activityui toneMint
class node_api,node_main,node_authroute,node_fileroute,node_shareroute,node_accessroute,node_activityroute,node_security toneRose
class node_database,node_storage,node_owner,node_recipient,node_google toneIndigo
```

## Components

### Browser application

- [Route application](https://github.com/aktdx/vaultkey/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in pages](https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/auth/AuthPages.tsx): `frontend/src/pages/auth/AuthPages.tsx`

### Identity and sessions

- [Auth context](https://github.com/aktdx/vaultkey/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Firebase client](https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/firebase.ts): `frontend/src/lib/firebase.ts`
- [Firebase verification](https://github.com/aktdx/vaultkey/blob/main/backend/app/firebase_service.py): `backend/app/firebase_service.py`

### File sharing

- [File management](https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/dashboard/FilesPage.tsx): `frontend/src/pages/dashboard/FilesPage.tsx`
- [File upload](https://github.com/aktdx/vaultkey/blob/main/frontend/src/components/upload/FileUpload.tsx): `frontend/src/components/upload/FileUpload.tsx`
- [Browser cryptography](https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/crypto.ts): `frontend/src/lib/crypto.ts`
- [Share management](https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/dashboard/SharesPage.tsx): `frontend/src/pages/dashboard/SharesPage.tsx`
- [Create share](https://github.com/aktdx/vaultkey/blob/main/frontend/src/components/shares/CreateShareModal.tsx): `frontend/src/components/shares/CreateShareModal.tsx`
- [Secure download](https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/SecureDownloadPage.tsx): `frontend/src/pages/SecureDownloadPage.tsx`
- [View-only viewer](https://github.com/aktdx/vaultkey/blob/main/frontend/src/components/shares/ViewOnlyViewer.tsx): `frontend/src/components/shares/ViewOnlyViewer.tsx`
- [Activity timeline](https://github.com/aktdx/vaultkey/blob/main/frontend/src/pages/dashboard/ActivityPage.tsx): `frontend/src/pages/dashboard/ActivityPage.tsx`

### API and policy

- [API client](https://github.com/aktdx/vaultkey/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [FastAPI application](https://github.com/aktdx/vaultkey/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [File routes](https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/files.py): `backend/app/routes/files.py`
- [Share routes](https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/shares.py): `backend/app/routes/shares.py`
- [Access routes](https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/access.py): `backend/app/routes/access.py`
- [Activity routes](https://github.com/aktdx/vaultkey/blob/main/backend/app/routes/activity.py): `backend/app/routes/activity.py`
- [Token security](https://github.com/aktdx/vaultkey/blob/main/backend/app/security.py): `backend/app/security.py`

### Persistence and storage

- [Relational database](https://github.com/aktdx/vaultkey/blob/main/backend/app/database.py): `backend/app/database.py`
- [Object storage adapter](https://github.com/aktdx/vaultkey/blob/main/backend/app/storage.py): `backend/app/storage.py`

### Other components

- **File owner**
- **Link recipient**
- **Firebase Auth**
- **Neon PostgreSQL**
- **Cloudflare R2**

## Connections

- File owner → Sign-in pages: signs in
- Sign-in pages → Auth context: calls
- Auth context → API client: auth requests
- Auth context → Firebase client: starts Google sign-in
- Firebase client → Firebase Auth: authenticates
- Auth context → API client: exchanges ID token
- Route application → File management: routes
- Route application → Share management: routes
- Route application → Secure download: routes
- Route application → Activity timeline: routes
- File owner → File upload: selects file
- File upload → Browser cryptography: encrypts locally
- File upload → API client: uploads ciphertext
- File owner → Create share: sets controls
- Create share → API client: creates share
- Share management → API client: manages shares
- Link recipient → Secure download: opens link
- Secure download → API client: requests access
- Secure download → Browser cryptography: decrypts locally
- Secure download → View-only viewer: presents content
- Activity timeline → API client: loads events
- API client → FastAPI application: sends requests
- FastAPI application → Authentication routes: dispatches
- FastAPI application → File routes: dispatches
- FastAPI application → Share routes: dispatches
- FastAPI application → Access routes: dispatches
- FastAPI application → Activity routes: dispatches
- Authentication routes → Token security: issues tokens
- Authentication routes → Firebase verification: verifies Google token
- Authentication routes → Relational database: reads and writes users
- File routes → Object storage adapter: stores ciphertext
- File routes → Relational database: records file metadata
- Share routes → Relational database: stores share controls
- Access routes → Relational database: checks limits and logs
- Access routes → Object storage adapter: streams ciphertext
- Activity routes → Relational database: reads activity
- Relational database → Neon PostgreSQL: queries
- Object storage adapter → Cloudflare R2: stores and streams objects