# ayulodhi/securefileshare architecture

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

- Interactive diagram: https://gitdiagram.com/ayulodhi/securefileshare
- Repository: https://github.com/ayulodhi/securefileshare

## Overview

SecureFileShare is a zero-knowledge file-sharing platform with a web client, a Java desktop client, and separate identity, file, sharing, and audit services. In the web workflow, users authenticate, upload encrypted content, manage files and keys, create or access share links, and review audit records. The backend separates those capabilities by service; the file service stores ciphertext and wrapped-key metadata, while the audit service verifies a hash chain. Edges are limited to relationships visible in excerpts, the source index, or README; client-to-service API wiring and some service interactions are not shown.

Main entry points: [`file-service/src/main/java/com/securefileshare/file/service/FileService.java`](https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/service/FileService.java) (File operations), [`auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java`](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java) (Account authentication), [`auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java`](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java) (Public key registry), [`web-app/src/App.tsx`](https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/App.tsx) (Web app router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web app router<br/>[App.tsx]"]
  node_webcrypto["Web cryptography"]
  node_webkeys["Key vault<br/>[keyVault.ts]"]
  node_desktop["Desktop client"]
  node_desktopcrypto["Desktop cryptography<br/>[CryptoEngine.java]"]
end

subgraph group_identity["Identity and keys"]
  node_authapi["Auth endpoints"]
  node_authlogic["Account authentication<br/>[AuthService.java]"]
  node_jwt["JWT issuance<br/>[JwtService.java]"]
  node_keyapi["Public key registry"]
  node_identitydb[("Identity database<br/>[User.java]")]
  node_keyvalidation["Key validation<br/>[KeyValidator.java]"]
end

subgraph group_files["Encrypted files"]
  node_fileapi["File endpoints"]
  node_filelogic["File operations<br/>[FileService.java]"]
  node_signature["Signature checks"]
  node_objectstore[("Ciphertext storage")]
  node_filedb[("File metadata<br/>[FileRecord.java]")]
end

subgraph group_sharing["Share links"]
  node_shareapi["Share endpoints"]
  node_sharelogic["Share lifecycle<br/>[ShareService.java]"]
  node_sharedb[("Share records<br/>[ShareRecord.java]")]
end

subgraph group_audit["Audit records"]
  node_auditapi["Audit endpoints"]
  node_auditlogic["Audit chain<br/>[AuditService.java]"]
  node_auditdb[("Audit records<br/>[AuditRecord.java]")]
end

node_user(("User"))
node_minio[("MinIO")]
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_web
node_web -.->|"encrypts locally"| node_webcrypto
node_webcrypto -->|"uses keys"| node_webkeys
node_user -.->|"uses"| node_desktop
node_desktop -.->|"encrypts locally"| node_desktopcrypto
node_authapi -->|"delegates to"| node_authlogic
node_authlogic -->|"issues tokens"| node_jwt
node_authlogic -->|"reads/writes"| node_identitydb
node_keyapi -->|"validates keys"| node_keyvalidation
node_keyapi -->|"resolves users"| node_identitydb
node_fileapi -->|"delegates to"| node_filelogic
node_filelogic -->|"verifies signatures"| node_signature
node_filelogic -->|"streams ciphertext"| node_objectstore
node_objectstore -.->|"stores objects"| node_minio
node_filelogic -->|"persists metadata"| node_filedb
node_filedb -.->|"stored in"| node_postgres
node_shareapi -->|"delegates to"| node_sharelogic
node_sharelogic -->|"reads/writes"| node_sharedb
node_sharedb -.->|"stored in"| node_postgres
node_auditapi -->|"delegates to"| node_auditlogic
node_auditlogic -->|"appends and verifies"| node_auditdb
node_auditdb -.->|"stored in"| node_postgres

click node_web "https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/App.tsx"
click node_webcrypto "https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/crypto/webCryptoService.ts"
click node_webkeys "https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/crypto/keyVault.ts"
click node_desktop "https://github.com/ayulodhi/securefileshare/tree/main/client-app/src/main/java/com/securefileshare/client"
click node_desktopcrypto "https://github.com/ayulodhi/securefileshare/blob/main/client-app/src/main/java/com/securefileshare/client/crypto/CryptoEngine.java"
click node_authapi "https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/controller/AuthController.java"
click node_authlogic "https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java"
click node_jwt "https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/security/JwtService.java"
click node_keyapi "https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java"
click node_identitydb "https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/entity/User.java"
click node_keyvalidation "https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/crypto/KeyValidator.java"
click node_fileapi "https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/controller/FileController.java"
click node_filelogic "https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/service/FileService.java"
click node_signature "https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/crypto/SignatureVerificationService.java"
click node_objectstore "https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/storage/MinioStorageService.java"
click node_filedb "https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/entity/FileRecord.java"
click node_shareapi "https://github.com/ayulodhi/securefileshare/blob/main/share-service/src/main/java/com/securefileshare/share/controller/ShareController.java"
click node_sharelogic "https://github.com/ayulodhi/securefileshare/blob/main/share-service/src/main/java/com/securefileshare/share/service/ShareService.java"
click node_sharedb "https://github.com/ayulodhi/securefileshare/blob/main/share-service/src/main/java/com/securefileshare/share/entity/ShareRecord.java"
click node_auditapi "https://github.com/ayulodhi/securefileshare/blob/main/audit-service/src/main/java/com/securefileshare/audit/controller/AuditController.java"
click node_auditlogic "https://github.com/ayulodhi/securefileshare/blob/main/audit-service/src/main/java/com/securefileshare/audit/service/AuditService.java"
click node_auditdb "https://github.com/ayulodhi/securefileshare/blob/main/audit-service/src/main/java/com/securefileshare/audit/entity/AuditRecord.java"

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_web,node_webcrypto,node_webkeys,node_desktop,node_desktopcrypto,node_user toneBlue
class node_authapi,node_authlogic,node_jwt,node_keyapi,node_identitydb,node_keyvalidation,node_minio,node_postgres toneAmber
class node_fileapi,node_filelogic,node_signature,node_objectstore,node_filedb toneMint
class node_shareapi,node_sharelogic,node_sharedb toneRose
class node_auditapi,node_auditlogic,node_auditdb toneIndigo
```

## Components

### User clients

- [Web app router](https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/App.tsx): `web-app/src/App.tsx`
- [Web cryptography](https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/crypto/webCryptoService.ts): `web-app/src/crypto/webCryptoService.ts`
- [Key vault](https://github.com/ayulodhi/securefileshare/blob/main/web-app/src/crypto/keyVault.ts): `web-app/src/crypto/keyVault.ts`
- [Desktop client](https://github.com/ayulodhi/securefileshare/tree/main/client-app/src/main/java/com/securefileshare/client): `client-app/src/main/java/com/securefileshare/client`
- [Desktop cryptography](https://github.com/ayulodhi/securefileshare/blob/main/client-app/src/main/java/com/securefileshare/client/crypto/CryptoEngine.java): `client-app/src/main/java/com/securefileshare/client/crypto/CryptoEngine.java`

### Identity and keys

- [Auth endpoints](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/controller/AuthController.java): `auth-service/src/main/java/com/securefileshare/auth/controller/AuthController.java`
- [Account authentication](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java): `auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java`
- [JWT issuance](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/security/JwtService.java): `auth-service/src/main/java/com/securefileshare/auth/security/JwtService.java`
- [Public key registry](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java): `auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java`
- [Identity database](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/entity/User.java): `auth-service/src/main/java/com/securefileshare/auth/entity/User.java`
- [Key validation](https://github.com/ayulodhi/securefileshare/blob/main/auth-service/src/main/java/com/securefileshare/auth/crypto/KeyValidator.java): `auth-service/src/main/java/com/securefileshare/auth/crypto/KeyValidator.java`

### Encrypted files

- [File endpoints](https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/controller/FileController.java): `file-service/src/main/java/com/securefileshare/file/controller/FileController.java`
- [File operations](https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/service/FileService.java): `file-service/src/main/java/com/securefileshare/file/service/FileService.java`
- [Signature checks](https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/crypto/SignatureVerificationService.java): `file-service/src/main/java/com/securefileshare/file/crypto/SignatureVerificationService.java`
- [Ciphertext storage](https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/storage/MinioStorageService.java): `file-service/src/main/java/com/securefileshare/file/storage/MinioStorageService.java`
- [File metadata](https://github.com/ayulodhi/securefileshare/blob/main/file-service/src/main/java/com/securefileshare/file/entity/FileRecord.java): `file-service/src/main/java/com/securefileshare/file/entity/FileRecord.java`

### Share links

- [Share endpoints](https://github.com/ayulodhi/securefileshare/blob/main/share-service/src/main/java/com/securefileshare/share/controller/ShareController.java): `share-service/src/main/java/com/securefileshare/share/controller/ShareController.java`
- [Share lifecycle](https://github.com/ayulodhi/securefileshare/blob/main/share-service/src/main/java/com/securefileshare/share/service/ShareService.java): `share-service/src/main/java/com/securefileshare/share/service/ShareService.java`
- [Share records](https://github.com/ayulodhi/securefileshare/blob/main/share-service/src/main/java/com/securefileshare/share/entity/ShareRecord.java): `share-service/src/main/java/com/securefileshare/share/entity/ShareRecord.java`

### Audit records

- [Audit endpoints](https://github.com/ayulodhi/securefileshare/blob/main/audit-service/src/main/java/com/securefileshare/audit/controller/AuditController.java): `audit-service/src/main/java/com/securefileshare/audit/controller/AuditController.java`
- [Audit chain](https://github.com/ayulodhi/securefileshare/blob/main/audit-service/src/main/java/com/securefileshare/audit/service/AuditService.java): `audit-service/src/main/java/com/securefileshare/audit/service/AuditService.java`
- [Audit records](https://github.com/ayulodhi/securefileshare/blob/main/audit-service/src/main/java/com/securefileshare/audit/entity/AuditRecord.java): `audit-service/src/main/java/com/securefileshare/audit/entity/AuditRecord.java`

### Other components

- **User**
- **MinIO**
- **PostgreSQL**

## Connections

- User → Web app router: uses (evidence: `web-app/src/App.tsx`)
- Web app router → Web cryptography: encrypts locally
- Web cryptography → Key vault: uses keys (evidence: `web-app/src/crypto/webCryptoService.ts`)
- User → Desktop client: uses
- Desktop client → Desktop cryptography: encrypts locally (evidence: `client-app/src/main/java/com/securefileshare/client/crypto/KeystoreService.java`)
- Auth endpoints → Account authentication: delegates to (evidence: `auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java`)
- Account authentication → JWT issuance: issues tokens (evidence: `auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java`)
- Account authentication → Identity database: reads/writes (evidence: `auth-service/src/main/java/com/securefileshare/auth/service/AuthService.java`)
- Public key registry → Key validation: validates keys (evidence: `auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java`)
- Public key registry → Identity database: resolves users (evidence: `auth-service/src/main/java/com/securefileshare/auth/service/KeyRegistryService.java`)
- File endpoints → File operations: delegates to (evidence: `file-service/src/main/java/com/securefileshare/file/controller/FileController.java`)
- File operations → Signature checks: verifies signatures (evidence: `file-service/src/main/java/com/securefileshare/file/service/FileService.java`)
- File operations → Ciphertext storage: streams ciphertext (evidence: `file-service/src/main/java/com/securefileshare/file/service/FileService.java`)
- Ciphertext storage → MinIO: stores objects
- File operations → File metadata: persists metadata (evidence: `file-service/src/main/java/com/securefileshare/file/service/FileService.java`)
- File metadata → PostgreSQL: stored in
- Share endpoints → Share lifecycle: delegates to (evidence: `share-service/src/main/java/com/securefileshare/share/controller/ShareController.java`)
- Share lifecycle → Share records: reads/writes (evidence: `share-service/src/main/java/com/securefileshare/share/service/ShareService.java`)
- Share records → PostgreSQL: stored in
- Audit endpoints → Audit chain: delegates to (evidence: `audit-service/src/main/java/com/securefileshare/audit/controller/AuditController.java`)
- Audit chain → Audit records: appends and verifies (evidence: `audit-service/src/main/java/com/securefileshare/audit/service/AuditService.java`)
- Audit records → PostgreSQL: stored in
