# kodevoid/formvault architecture

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

- Interactive diagram: https://gitdiagram.com/kodevoid/formvault
- Repository: https://github.com/kodevoid/formvault

## Overview

##### Project Type and Purpose
- FormVault is a full-stack, developer-first form-handling service.
- Frontend: React/Vite app providing form embedding, encryption, and SDK hooks.
- Backend: Rust (Actix-web) service offering zero-knowledge encrypted RESTful API, webhook support, and data storage.

##### File Structure
- Top-level directories:
- frontend/ — React + Vite + JavaScript SDK code
- backend/ — Rust service with Cargo setup, Diesel migrations, Docker support
- backend/data/formvault.db: Embedded SQLite database (for local/dev).
- backend/migrations/: SQL scripts (Init, developer_init).
- backend/src/handlers, routes, repositories, models: MVC-style separation.
- frontend/src/components: UI components (Home, Issues, Contributions, Navbar, etc.)
- Docker artifacts: backend/Dockerfile, compose.yaml; .env for secrets.

##### README for Additional Insights
- Core features: zero-knowledge encryption on the client, RESTful API, webhooks, custom fields.
- Planned SDKs: JavaScript (present), Python/Rust (future).
- Security focus: end-to-end encryption, privacy by design.

##### Main Components
a. Frontend Client
- React/Vite SPA (App.jsx, components/)
- JavaScript SDK: performs AES/RSA encryption before submission
- Public assets served via index.html
b. Backend API Service
- Actix-web server (main.rs, handlers, routes)
- Business logic: configuration.rs, webhook.rs
- Repositories layer: form repository, developer repository, encryption utilities
- Database layer: Diesel over SQLite (or Postgres in prod)
c. Database
- SQLite (data/formvault.db) for dev; abstract to Postgres/MySQL for prod
- Migration scripts in backend/migrations/
d. External Services
- Webhook targets: third-party endpoints notified on submission
- (Future) Monitoring/Logging/Audit service
e. Development/Deployment
- Docker & Docker Compose (backend/Dockerfile, compose.yaml)
- .env for secrets (encryption keys, DB URL)

##### Relationships and Data Flow
1. User fills form in Frontend →
2. SDK encrypts payload →
3. Encrypted POST /submissions → Backend API →
4. Backend validates, stores encrypted blob in DB →
5. Backend triggers webhook (outbound HTTP) → External system →
6. Admin/dev dashboards fetch decrypted data via API (with key) → Frontend UI

##### Architectural Patterns & Design Principles
- Layered Architecture: Presentation (frontend), API, Domain (handlers/models), Persistence (repositories/DB).
- Zero-Knowledge Encryption: client-side encryption, backend stores ciphertext only.
- Modular Rust code: src/handlers, routes, repositories, models.
- CI/CD via Docker: containerized development & deployment.
- RESTful API design: stateless endpoints, clear resource modeling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User"]:::actor

    %% Frontend Layer
    subgraph "Frontend Client" 
        direction TB
        App["App.jsx"]:::frontend
        Main["main.jsx"]:::frontend
        Components["components/"]:::frontend
        IndexHTML["index.html"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
        ESLintConfig["eslint.config.js"]:::frontend
        PublicAssets["public/"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API Service"
        direction TB
        MainRS["main.rs"]:::backend
        LibRS["lib.rs"]:::backend

        subgraph "Handlers"
            direction TB
            HandlersMod["handlers/mod.rs"]:::backend
            ConfigHandler["handlers/configuration.rs"]:::backend
        end

        subgraph "Routes"
            direction TB
            RoutesMod["routes/mod.rs"]:::backend
            ConfigRoute["routes/configuration.rs"]:::backend
        end

        WebhookRS["webhook.rs"]:::backend

        subgraph "Repositories"
            direction TB
            RepoMod["repositories/mod.rs"]:::backend
            FormRepo["repositories/form.rs"]:::backend
            DevRepo["repositories/developers_repository.rs"]:::backend
            EncryptionRepo["repositories/encryption.rs"]:::backend
        end

        subgraph "Domain Models"
            direction TB
            ModelMod["models/mod.rs"]:::backend
            FormVaultModel["models/formvault.rs"]:::backend
            subgraph "Forms Models"
                direction TB
                FieldDef["models/forms/field_definition.rs"]:::backend
                FormSchema["models/forms/form_schema.rs"]:::backend
                SubmissionModel["models/forms/submission.rs"]:::backend
            end
            DevModel["models/users/developer.rs"]:::backend
        end
    end

    %% Persistence Layer
    subgraph "Database & Migrations"
        direction TB
        DB["formvault.db"]:::db
        M1Up["20250829204726_Init.up.sql"]:::db
        M1Down["20250829204726_Init.down.sql"]:::db
        M2Up["20250830171842_developer_init.up.sql"]:::db
        M2Down["20250830171842_developer_init.down.sql"]:::db
    end

    %% Deployment
    subgraph "Development & Deployment"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        Compose["compose.yaml"]:::infra
        Env[".env"]:::infra
        Dockerignore[".dockerignore"]:::infra
        DocDocker["README.Docker.md"]:::infra
    end

    %% Tests
    subgraph "Tests"
        direction TB
        HealthCheck["health_check.rs"]:::tests
        ApiRoutesTest["api_routes.rs"]:::tests
        SubscribeDev["subscribe_dev.rs"]:::tests
    end

    %% External Services
    External["Webhook Receiver"]:::external

    %% Data Flow
    User -->|"fills form"| App
    App -->|"calls SDK encryption"| Main
    Main -->|"HTTPS JSON (encrypted)"| MainRS
    MainRS -->|"dispatch to handlers"| HandlersMod
    HandlersMod -->|"uses routes"| RoutesMod
    HandlersMod -->|"business logic"| WebhookRS
    HandlersMod -->|"persist data"| RepoMod
    RepoMod -->|"stores ciphertext"| DB
    WebhookRS -->|"outbound HTTP"| External
    Compose --> MainRS
    Compose --> DB

    %% Click Events
    click App "https://github.com/kodevoid/formvault/blob/master/frontend/src/App.jsx"
    click Main "https://github.com/kodevoid/formvault/blob/master/frontend/src/main.jsx"
    click Components "https://github.com/kodevoid/formvault/tree/master/frontend/src/components/"
    click IndexHTML "https://github.com/kodevoid/formvault/blob/master/frontend/index.html"
    click ViteConfig "https://github.com/kodevoid/formvault/blob/master/frontend/vite.config.js"
    click ESLintConfig "https://github.com/kodevoid/formvault/blob/master/frontend/eslint.config.js"
    click PublicAssets "https://github.com/kodevoid/formvault/tree/master/frontend/public/"
    click MainRS "https://github.com/kodevoid/formvault/blob/master/backend/src/main.rs"
    click LibRS "https://github.com/kodevoid/formvault/blob/master/backend/src/lib.rs"
    click HandlersMod "https://github.com/kodevoid/formvault/blob/master/backend/src/handlers/mod.rs"
    click ConfigHandler "https://github.com/kodevoid/formvault/blob/master/backend/src/handlers/configuration.rs"
    click RoutesMod "https://github.com/kodevoid/formvault/blob/master/backend/src/routes/mod.rs"
    click ConfigRoute "https://github.com/kodevoid/formvault/blob/master/backend/src/routes/configuration.rs"
    click WebhookRS "https://github.com/kodevoid/formvault/blob/master/backend/src/webhook.rs"
    click RepoMod "https://github.com/kodevoid/formvault/blob/master/backend/src/repositories/mod.rs"
    click FormRepo "https://github.com/kodevoid/formvault/blob/master/backend/src/repositories/form.rs"
    click DevRepo "https://github.com/kodevoid/formvault/blob/master/backend/src/repositories/developers_repository.rs"
    click EncryptionRepo "https://github.com/kodevoid/formvault/blob/master/backend/src/repositories/encryption.rs"
    click ModelMod "https://github.com/kodevoid/formvault/blob/master/backend/src/models/mod.rs"
    click FormVaultModel "https://github.com/kodevoid/formvault/blob/master/backend/src/models/formvault.rs"
    click FieldDef "https://github.com/kodevoid/formvault/blob/master/backend/src/models/forms/field_definition.rs"
    click FormSchema "https://github.com/kodevoid/formvault/blob/master/backend/src/models/forms/form_schema.rs"
    click SubmissionModel "https://github.com/kodevoid/formvault/blob/master/backend/src/models/forms/submission.rs"
    click DevModel "https://github.com/kodevoid/formvault/blob/master/backend/src/models/users/developer.rs"
    click DB "https://github.com/kodevoid/formvault/blob/master/backend/data/formvault.db"
    click M1Up "https://github.com/kodevoid/formvault/blob/master/backend/migrations/20250829204726_Init.up.sql"
    click M1Down "https://github.com/kodevoid/formvault/blob/master/backend/migrations/20250829204726_Init.down.sql"
    click M2Up "https://github.com/kodevoid/formvault/blob/master/backend/migrations/20250830171842_developer_init.up.sql"
    click M2Down "https://github.com/kodevoid/formvault/blob/master/backend/migrations/20250830171842_developer_init.down.sql"
    click Dockerfile "https://github.com/kodevoid/formvault/tree/master/backend/Dockerfile"
    click Compose "https://github.com/kodevoid/formvault/blob/master/backend/compose.yaml"
    click Env "https://github.com/kodevoid/formvault/blob/master/backend/.env"
    click Dockerignore "https://github.com/kodevoid/formvault/blob/master/backend/.dockerignore"
    click DocDocker "https://github.com/kodevoid/formvault/blob/master/backend/README.Docker.md"
    click HealthCheck "https://github.com/kodevoid/formvault/blob/master/backend/tests/health_check.rs"
    click ApiRoutesTest "https://github.com/kodevoid/formvault/blob/master/backend/tests/api_routes.rs"
    click SubscribeDev "https://github.com/kodevoid/formvault/blob/master/backend/tests/subscribe_dev.rs"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#0366d6,color:#000
    classDef backend fill:#BDECB6,stroke:#228B22,color:#000
    classDef db fill:#FFECB3,stroke:#FF8C00,color:#000
    classDef infra fill:#E0E0E0,stroke:#757575,color:#000
    classDef tests fill:#D8BFD8,stroke:#9370DB,color:#000
    classDef external fill:#F5F5F5,stroke:#A9A9A9,color:#000
    classDef actor fill:#FFFFFF,stroke:#000000,color:#000,stroke-dasharray: 5 5
```
