# marcovdss/crypofolder architecture

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

- Interactive diagram: https://gitdiagram.com/marcovdss/crypofolder
- Repository: https://github.com/marcovdss/crypofolder

## Overview

##### Project Type and Purpose
- This project is a specialized security utility focused on file and folder encryption/decryption.
- It is a focused library/tool (with functions like encrypt_folder and decrypt_folder) meant for protecting file contents using strong cryptographic standards.
- The goal is to securely encrypt files in a folder and later decrypt them, ensuring confidentiality and integrity through AES-256-GCM and key derivation with PBKDF2.

##### Analyzing the File Structure
- At the root, you have the LICENSE and README, which provide licensing and usage information.
- The "crypo_folder" directory contains the core functionality:
- crypo_folder.py: Likely includes the main logic for both encryption and decryption.
- requirements.txt: Lists Python dependencies (e.g., the cryptography package).
- There is no separate frontend/backend or complex multi-layer structure; instead, the design focuses on core cryptographic operations.

##### Key Components
- File System Interface:
- Input: Accepts a folder path containing files to encrypt or decrypt.
- Output: Processes files by removing originals post-encryption and generating .enc files; reverses the process for decryption.
- Encryption Engine (in crypo_folder.py):
- AES-256-GCM algorithm: Encrypts individual files ensuring both confidential data and its integrity are protected.
- Random IV (Initialization Vector) generation for each file.
- PBKDF2-based key derivation: Derives a 32-byte AES key using a user-supplied password and random salt.
- Metadata Management:
- "encryption_key.json": Handles secure storage of metadata (such as the generated salt) required for decryption.
- Deletion and Cleanup:
- For encryption: Deletes original plaintext files.
- For decryption: Deletes the metadata file (encryption_key.json) after restoring the original files.

- Major module as a distinct component:
- “User / Client” initiating encryption/decryption via function calls.
- “File Handler” that interacts with the file system to read and write files.
- “Encryption Module” that contains:
o Key Derivation Submodule (PBKDF2, salt generation).
o AES-256-GCM Encryption and Decryption Submodule (handles encryption with random IV, attaches authentication tag).
- “Metadata Manager” that reads/writes the encryption_key.json file.
- From the “User” to “File Handler” indicating the folder path is provided.
- From “File Handler” to “Encryption Module” for processing each file.
- From “Encryption Module” back to “File Handler” for outputting encrypted (.enc) files.
- During decryption, reverse flows: Read metadata from “Metadata Manager,” pass to “Encryption Module” for decryption, and restore files via “File Handler.”

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each component is tasked with a specific responsibility—file I/O, encryption, metadata management.
- Security Best Practices: The design clearly separates sensitive operations like key derivation (using PBKDF2) and secure handling of random IVs with the encryption module.
- Modularity: The cryptographic operations are encapsulated in a single module (crypo_folder.py), making it easier to modify or extend if required.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User/Client"]:::external
    FH["File Handler (File System Interface)"]:::fileio

    subgraph "Encryption Engine"
        EM["Encryption Module (AES-256-GCM & PBKDF2)"]:::crypto
        KD["Key Derivation (PBKDF2, Salt Generation)"]:::crypto
        AES["AES-256-GCM Operation"]:::crypto
        EM --> KD
        EM --> AES
    end

    MM["Metadata Manager (encryption_key.json)"]:::metadata

    U -->|"provideFolder"| FH
    FH -->|"readFiles"| EM
    AES -->|"outputFiles"| FH
    AES -->|"sendMetadata"| MM
    MM -->|"provideMetadata"| AES

    %% Click Events
    click FH "https://github.com/marcovdss/crypofolder/blob/main/crypo_folder/crypo_folder.py"
    click EM "https://github.com/marcovdss/crypofolder/blob/main/crypo_folder/crypo_folder.py"
    click MM "https://github.com/marcovdss/crypofolder/blob/main/crypo_folder/crypo_folder.py"

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef fileio fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef crypto fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef metadata fill:#e6ffe6,stroke:#009900,stroke-width:2px;
```
