# sjasonp/foldersguard architecture

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

- Interactive diagram: https://gitdiagram.com/sjasonp/foldersguard
- Repository: https://github.com/sjasonp/foldersguard

## Overview

FoldersGuard is an experimental desktop and CLI application for encrypting folders into portable UUID-named content trees, with separate encrypted metadata databases. The main workflow creates or imports a project, encrypts its source, and then supports inspection, verification, decryption, export, and modification; sharing packages selected encrypted entries into share-scoped databases. The desktop UI calls Go through the Wails bridge, while the CLI offers automation. The README documents these capabilities; sampled source confirms parts of the UI, project service, and change-application flows, so unsampled internal wiring is kept conservative.

Main entry points: [`internal/app`](https://github.com/sjasonp/foldersguard/tree/main/internal/app) (Application service), [`internal/app/service_projects.go`](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_projects.go) (Project workflows), [`internal/db/open.go`](https://github.com/sjasonp/foldersguard/blob/main/internal/db/open.go) (Encrypted databases), [`internal/app/service_project_browser.go`](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_project_browser.go) (Project browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_webui["Desktop WebUI<br/>[App.tsx]"]
  node_project_hooks["Project workflows"]
  node_wails_bridge["Wails bindings<br/>[App.js]"]
  node_cli["CLI commands<br/>[cli.go]"]
  node_wails_app["Desktop API<br/>[app.go]"]
end

subgraph group_operations["Project operations"]
  node_app_service["Application service"]
  node_project_service["Project workflows"]
  node_browser_service["Project browser"]
  node_change_service["Apply changes"]
  node_sharing_service["Share workflows<br/>[service_shares.go]"]
  node_share_create["Create shares"]
end

subgraph group_security["Content and security"]
  node_project_engine["Project engine<br/>[execute.go]"]
  node_content_crypto["Content encryption<br/>[encrypt.go]"]
  node_crypto_keys["Cryptographic keys<br/>[keys.go]"]
  node_verification["Integrity verification<br/>[verify.go]"]
  node_storage_ops["Content operations"]
end

subgraph group_metadata["Metadata and storage"]
  node_metadata_db[("Encrypted databases<br/>[open.go]")]
  node_storage[("Metadata store<br/>[store.go]")]
  node_planner["Project planning<br/>[planner.go]"]
  node_backup["Project backups<br/>[backup.go]"]
end

node_desktop_user(("Desktop user"))
node_cli_user(("CLI user"))
node_filesystem["Local files"]

node_desktop_user -->|"uses"| node_webui
node_webui -->|"starts workflows"| node_project_hooks
node_project_hooks -->|"invokes operations"| node_wails_bridge
node_wails_bridge -->|"dispatches calls"| node_wails_app
node_cli_user -->|"runs commands"| node_cli
node_cli -->|"requests operations"| node_app_service
node_wails_app -->|"delegates calls"| node_app_service
node_app_service -->|"handles projects"| node_project_service
node_app_service -->|"opens browser"| node_browser_service
node_app_service -->|"applies changes"| node_change_service
node_app_service -->|"handles shares"| node_sharing_service
node_app_service -->|"creates shares"| node_share_create
node_project_service -->|"plans projects"| node_planner
node_project_service -->|"executes encryption"| node_project_engine
node_project_service -->|"verifies content"| node_verification
node_project_service -->|"reads databases"| node_metadata_db
node_project_service -->|"reads and writes"| node_filesystem
node_project_engine -->|"encrypts content"| node_content_crypto
node_content_crypto -->|"uses keys"| node_crypto_keys
node_verification -->|"checks encrypted objects"| node_filesystem
node_verification -->|"reads metadata"| node_metadata_db
node_browser_service -->|"opens project database"| node_metadata_db
node_browser_service -->|"browses metadata"| node_storage
node_change_service -->|"plans metadata edits"| node_storage
node_change_service -->|"applies content edits"| node_storage_ops
node_storage_ops -->|"changes encrypted tree"| node_filesystem
node_sharing_service -->|"reads share database"| node_metadata_db
node_share_create -->|"writes share database"| node_metadata_db
node_share_create -->|"selects project entries"| node_storage
node_app_service -->|"manages backups"| node_backup
node_backup -->|"stores backups"| node_filesystem

click node_webui "https://github.com/sjasonp/foldersguard/blob/main/frontend/src/App.tsx"
click node_project_hooks "https://github.com/sjasonp/foldersguard/blob/main/frontend/src/hooks/useProjectActions.ts"
click node_wails_bridge "https://github.com/sjasonp/foldersguard/blob/main/frontend/wailsjs/go/main/App.js"
click node_cli "https://github.com/sjasonp/foldersguard/blob/main/internal/cli/cli.go"
click node_wails_app "https://github.com/sjasonp/foldersguard/blob/main/app.go"
click node_app_service "https://github.com/sjasonp/foldersguard/tree/main/internal/app"
click node_project_service "https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_projects.go"
click node_browser_service "https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_project_browser.go"
click node_change_service "https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_project_changes.go"
click node_sharing_service "https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_shares.go"
click node_share_create "https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_share_create.go"
click node_project_engine "https://github.com/sjasonp/foldersguard/blob/main/internal/project/execute.go"
click node_content_crypto "https://github.com/sjasonp/foldersguard/blob/main/internal/content/encrypt.go"
click node_crypto_keys "https://github.com/sjasonp/foldersguard/blob/main/internal/crypto/keys.go"
click node_verification "https://github.com/sjasonp/foldersguard/blob/main/internal/project/verify.go"
click node_storage_ops "https://github.com/sjasonp/foldersguard/blob/main/internal/app/content_operations.go"
click node_metadata_db "https://github.com/sjasonp/foldersguard/blob/main/internal/db/open.go"
click node_storage "https://github.com/sjasonp/foldersguard/blob/main/internal/storage/store.go"
click node_planner "https://github.com/sjasonp/foldersguard/blob/main/internal/project/planner.go"
click node_backup "https://github.com/sjasonp/foldersguard/blob/main/internal/app/backup.go"

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_webui,node_project_hooks,node_wails_bridge,node_cli,node_wails_app,node_desktop_user,node_cli_user toneBlue
class node_app_service,node_project_service,node_browser_service,node_change_service,node_sharing_service,node_share_create toneAmber
class node_project_engine,node_content_crypto,node_crypto_keys,node_verification,node_storage_ops toneMint
class node_metadata_db,node_storage,node_planner,node_backup toneRose
class node_filesystem toneIndigo
```

## Components

### User interfaces

- [Desktop WebUI](https://github.com/sjasonp/foldersguard/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Project workflows](https://github.com/sjasonp/foldersguard/blob/main/frontend/src/hooks/useProjectActions.ts): `frontend/src/hooks/useProjectActions.ts`
- [Wails bindings](https://github.com/sjasonp/foldersguard/blob/main/frontend/wailsjs/go/main/App.js): `frontend/wailsjs/go/main/App.js`
- [CLI commands](https://github.com/sjasonp/foldersguard/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Desktop API](https://github.com/sjasonp/foldersguard/blob/main/app.go): `app.go`

### Project operations

- [Application service](https://github.com/sjasonp/foldersguard/tree/main/internal/app): `internal/app`
- [Project workflows](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_projects.go): `internal/app/service_projects.go`
- [Project browser](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_project_browser.go): `internal/app/service_project_browser.go`
- [Apply changes](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_project_changes.go): `internal/app/service_project_changes.go`
- [Share workflows](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_shares.go): `internal/app/service_shares.go`
- [Create shares](https://github.com/sjasonp/foldersguard/blob/main/internal/app/service_share_create.go): `internal/app/service_share_create.go`

### Content and security

- [Project engine](https://github.com/sjasonp/foldersguard/blob/main/internal/project/execute.go): `internal/project/execute.go`
- [Content encryption](https://github.com/sjasonp/foldersguard/blob/main/internal/content/encrypt.go): `internal/content/encrypt.go`
- [Cryptographic keys](https://github.com/sjasonp/foldersguard/blob/main/internal/crypto/keys.go): `internal/crypto/keys.go`
- [Integrity verification](https://github.com/sjasonp/foldersguard/blob/main/internal/project/verify.go): `internal/project/verify.go`
- [Content operations](https://github.com/sjasonp/foldersguard/blob/main/internal/app/content_operations.go): `internal/app/content_operations.go`

### Metadata and storage

- [Encrypted databases](https://github.com/sjasonp/foldersguard/blob/main/internal/db/open.go): `internal/db/open.go`
- [Metadata store](https://github.com/sjasonp/foldersguard/blob/main/internal/storage/store.go): `internal/storage/store.go`
- [Project planning](https://github.com/sjasonp/foldersguard/blob/main/internal/project/planner.go): `internal/project/planner.go`
- [Project backups](https://github.com/sjasonp/foldersguard/blob/main/internal/app/backup.go): `internal/app/backup.go`

### Other components

- **Desktop user**
- **CLI user**
- **Local files**

## Connections

- Desktop user → Desktop WebUI: uses
- Desktop WebUI → Project workflows: starts workflows
- Project workflows → Wails bindings: invokes operations
- Wails bindings → Desktop API: dispatches calls
- CLI user → CLI commands: runs commands
- CLI commands → Application service: requests operations
- Desktop API → Application service: delegates calls
- Application service → Project workflows: handles projects
- Application service → Project browser: opens browser
- Application service → Apply changes: applies changes
- Application service → Share workflows: handles shares
- Application service → Create shares: creates shares
- Project workflows → Project planning: plans projects
- Project workflows → Project engine: executes encryption
- Project workflows → Integrity verification: verifies content
- Project workflows → Encrypted databases: reads databases
- Project workflows → Local files: reads and writes
- Project engine → Content encryption: encrypts content
- Content encryption → Cryptographic keys: uses keys
- Integrity verification → Local files: checks encrypted objects
- Integrity verification → Encrypted databases: reads metadata
- Project browser → Encrypted databases: opens project database
- Project browser → Metadata store: browses metadata
- Apply changes → Metadata store: plans metadata edits
- Apply changes → Content operations: applies content edits
- Content operations → Local files: changes encrypted tree
- Share workflows → Encrypted databases: reads share database
- Create shares → Encrypted databases: writes share database
- Create shares → Metadata store: selects project entries
- Application service → Project backups: manages backups
- Project backups → Local files: stores backups