# hudikhq/hoodik architecture

> Architecture diagram of the GitHub repository hudikhq/hoodik, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hudikhq/hoodik
- Repository: https://github.com/hudikhq/hoodik

## Overview

##### Project Type and Purpose
- Hoodik is a full-stack, self-hosted cloud-storage solution combining:
- A Vue.js Single-Page Application (frontend)
- A Rust/Actix Web backend composed of multiple workspace crates
- A relational database (SQLite or Postgres)
- File-system and chunked storage
- External dependencies (SMTP, reverse proxy)

##### Top-Level Architecture Components
A. Frontend (Web SPA)
- Vue.js app (under `web/src`)
- cryptfns WASM module (under `web/services/cryptfns`)
- E2E tests (Cypress)
B. Backend (Rust/Actix Web Server)
- Main server binary (`hoodik/src/main.rs`)
- Configuration loader (`config` crate)
- Context (request context, `context` crate)
- Routing & APIs (Actix Web via `util/actix.rs`)
- Domain modules (each a Rust crate):
- Authentication (`auth` crate)
- Administration UI API (`admin` crate)
- File storage (`storage` crate)
- Link sharing (`links` crate)
- Email sending (`email` crate)
- Settings & policies (`settings` crate)
- Shared libraries:
- Entities & types (`entity` crate)
- Encryption primitives (`cryptfns` crate, server side)
- Filesystem abstraction (`fs` crate)
- Error handling (`error` crate)
- Utility functions (`util` crate)
C. Data Stores
- Relational database (SQLite or Postgres)
- Local disk for encrypted file chunks
D. External Services
- SMTP server for emails
- Reverse proxy (e.g., Nginx)
- Clients (browsers)

##### Component Relationships & Data Flows
1. Browser → HTTPS → Actix Web Server (REST/WebSocket endpoints)
2. Server → Database (queries via repository modules in each crate)
3. Server → Local disk (encrypted chunks via `fs` crate)
4. Server → SMTP (via `email` crate’s SMTP provider)
5. Server (cryptfns) ↔ Client (WASM cryptfns) for end-to-end encryption
6. Server → Migration CLI (one-way for DB schema updates)

##### Architectural Patterns
- Modular, Cargo-workspace structure: each feature is a Rust crate.
- Repository pattern: data access lives in `repository` modules inside each crate.
- Tokenization + hashed indexes for secure searching (in `storage` + `entity`).
- Hybrid encryption flow: AES per file + RSA per user/link (in `cryptfns`).
- Chunked file upload/download for parallelism.
- Feature toggles: optional server-side encryption fallback.
- Configuration injection via environment (`config` crate) and dependency crates.

##### Technologies & Frameworks to Call Out
- Rust & Cargo workspaces
- Actix Web (HTTP server)
- Vue.js (frontend) + Vite
- WebAssembly for client crypto
- SQLite / Postgres
- SMTP (email)
- Cypress (E2E tests)
- Docker / Docker Compose / GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hoodik System"
        subgraph "Frontend (Web SPA)"
            Browser["Browser"]:::frontend
            VueApp["Vue.js SPA"]:::frontend
            CryptWASM["WASM Crypto Module"]:::frontend
            E2E["E2E Tests (Cypress)"]:::frontend
            CI["Cypress Config"]:::frontend
        end

        subgraph "Rust Server"
            Main["Actix Server\nhoodik/src/main.rs"]:::backend
            Config["Config Loader\nconfig/src/config.rs"]:::backend
            Context["Request Context\ncontext/src/lib.rs"]:::backend
            UtilActix["Routing & API Helpers\nutil/src/actix.rs"]:::backend

            subgraph "Domain Modules"
                Auth["Authentication\nauth/src/lib.rs"]:::backend
                Admin["Admin UI API\nadmin/src/lib.rs"]:::backend
                Storage["File Storage\nstorage/src/lib.rs"]:::backend
                Links["Link Sharing\nlinks/src/lib.rs"]:::backend
                EmailMod["Email Module\nemail/src/lib.rs"]:::backend
                Settings["Settings & Policies\nsettings/src/lib.rs"]:::backend
                EmailSMTP["SMTP Sender\nemail/src/senders/smtp.rs"]:::backend
            end

            subgraph "Shared Libraries"
                Entity["Entities & Types\nentity/src/lib.rs"]:::backend
                CryptSrv["Server Crypto\ncryptfns/src/lib.rs"]:::backend
                FS["Filesystem Abstraction\nfs/src/lib.rs"]:::backend
                FSProv["Disk Provider\nfs/src/providers/fs.rs"]:::backend
                Err["Error Handling\nerror/src/lib.rs"]:::backend
                Util["Utility Functions\nutil/src/lib.rs"]:::backend
            end

            MigCLI["Migration CLI\nmigration/src/main.rs"]:::backend
        end

        subgraph "Data Stores"
            DB["Relational Database\n(SQLite/Postgres)"]:::datastore
            Disk["Local Disk Storage\n(encrypted chunks)"]:::datastore
        end

        subgraph "External Services"
            SMTP["SMTP Server"]:::external
            Proxy["Reverse Proxy (Nginx)"]:::external
        end
    end

    %% Connections
    Browser -->|HTTPS| Main
    VueApp -->|serves UI| Browser
    Main -->|SQL| DB
    Main -->|read/write chunks| Disk
    Main -->|SMTP| SMTP
    Main -->|DB migrations| MigCLI
    CryptWASM <-->|E2E Encryption| CryptSrv
    Browser <-->|WASM Crypto| CryptWASM

    %% Click Events
    click VueApp "https://github.com/hudikhq/hoodik/tree/master/web/src"
    click CryptWASM "https://github.com/hudikhq/hoodik/blob/master/web/services/cryptfns/wasm.ts"
    click E2E "https://github.com/hudikhq/hoodik/tree/master/web/cypress"
    click CI "https://github.com/hudikhq/hoodik/blob/master/cypress.config.ts"
    click Main "https://github.com/hudikhq/hoodik/blob/master/hoodik/src/main.rs"
    click Config "https://github.com/hudikhq/hoodik/blob/master/config/src/config.rs"
    click Context "https://github.com/hudikhq/hoodik/blob/master/context/src/lib.rs"
    click UtilActix "https://github.com/hudikhq/hoodik/blob/master/util/src/actix.rs"
    click Auth "https://github.com/hudikhq/hoodik/blob/master/auth/src/lib.rs"
    click Admin "https://github.com/hudikhq/hoodik/blob/master/admin/src/lib.rs"
    click Storage "https://github.com/hudikhq/hoodik/blob/master/storage/src/lib.rs"
    click Links "https://github.com/hudikhq/hoodik/blob/master/links/src/lib.rs"
    click EmailMod "https://github.com/hudikhq/hoodik/blob/master/email/src/lib.rs"
    click EmailSMTP "https://github.com/hudikhq/hoodik/blob/master/email/src/senders/smtp.rs"
    click Settings "https://github.com/hudikhq/hoodik/blob/master/settings/src/lib.rs"
    click Entity "https://github.com/hudikhq/hoodik/blob/master/entity/src/lib.rs"
    click CryptSrv "https://github.com/hudikhq/hoodik/blob/master/cryptfns/src/lib.rs"
    click FS "https://github.com/hudikhq/hoodik/blob/master/fs/src/lib.rs"
    click FSProv "https://github.com/hudikhq/hoodik/blob/master/fs/src/providers/fs.rs"
    click Err "https://github.com/hudikhq/hoodik/blob/master/error/src/lib.rs"
    click Util "https://github.com/hudikhq/hoodik/blob/master/util/src/lib.rs"
    click MigCLI "https://github.com/hudikhq/hoodik/blob/master/migration/src/main.rs"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#000,stroke-width:1px
    classDef datastore fill:#fff3cd,stroke:#000,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#000,stroke-width:1px
```
