# zemariavg/notist-client architecture

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

- Interactive diagram: https://gitdiagram.com/zemariavg/notist-client
- Repository: https://github.com/zemariavg/notist-client

## Overview

##### Project type and purpose
- This is a command‐line client tool for securely creating, reading, editing, listing, backing up, and managing encrypted notes.
- It bundles a small “cryptolib” encryption library, a set of action handlers, utility modules, and local filesystem storage of notes and keys.

##### Main components
a. CLI Frontend (app.py)
- Parses user commands and dispatches to the appropriate action in the `actions/` folder.
b. Actions Layer (`actions/`)
- One module per operation (create, read, edit, list, backup, integrity check, add collaborator, retrieve).
- Each action calls into the cryptolib or utils to perform its task.
c. Cryptography Library (`cryptolib/`)
- Core encryption/decryption routines (`protect.py`, `unprotect.py`, `check.py`, `notist.py`).
- Utility subpackage for file I/O, key management, parsing (`utils/cryptoutils.py`, `utils/file.py`, `utils/noteparser.py`).
- Built‐in tests under `cryptolib/test/`.
d. General Utilities (`utils/noteutils.py`)
- Higher‐level helpers for note formatting, metadata injection, etc., used by actions.
e. Local Storage
- Notes stored as JSON on the filesystem.
- User keypairs under `keys/` directory.
- Configuration (`config.py`) governs default file paths and parameters.

##### Key relationships and data flows
- User invokes `python3 app.py <action> [args]`.
- CLI parses input → loads config → instantiates the chosen action.
- Action retrieves or writes note files via `utils` or direct file I/O.
- For encryption/decryption, action calls `cryptolib.protect` or `cryptolib.unprotect`, which in turn uses key files from `keys/` and low‐level routines in `cryptolib/utils`.
- Output (encrypted JSON, plaintext notes, integrity reports) is printed to stdout or saved back to disk.

##### Architectural patterns and design principles
- Modular layering: CLI → Action modules → Crypto library + Utils → Filesystem.
- Single‐Responsibility: each action module manages one command.
- Separation of concerns: cryptographic logic lives in `cryptolib`, UI and command parsing live in `app.py`, file‐format logic in `utils`.
- Extensibility: Adding a new action just means dropping a new script in `actions/` that conforms to the existing interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Config
    subgraph "Python 3 Runtime"
        CLI["CLI Frontend\napp.py"]:::frontend
        click CLI "https://github.com/zemariavg/notist-client/blob/main/app.py"
        CFG["Configuration\nconfig.py"]:::utils
        click CFG "https://github.com/zemariavg/notist-client/blob/main/config.py"
    end

    CLI -.->|"load config"| CFG

    %% Actions Layer
    subgraph "Actions Layer" 
        CN["Create Note\ncreate_note.py"]:::frontend
        click CN "https://github.com/zemariavg/notist-client/blob/main/actions/create_note.py"
        RN["Read Note\nread_note.py"]:::frontend
        click RN "https://github.com/zemariavg/notist-client/blob/main/actions/read_note.py"
        EN["Edit Note\nedit_note.py"]:::frontend
        click EN "https://github.com/zemariavg/notist-client/blob/main/actions/edit_note.py"
        LN["List Notes\nlist_notes.py"]:::frontend
        click LN "https://github.com/zemariavg/notist-client/blob/main/actions/list_notes.py"
        BN["Backup Notes\nbackup_notes.py"]:::frontend
        click BN "https://github.com/zemariavg/notist-client/blob/main/actions/backup_notes.py"
        CI["Check Integrity\ncheck_integrity.py"]:::frontend
        click CI "https://github.com/zemariavg/notist-client/blob/main/actions/check_integrity.py"
        AC["Add Collaborator\nadd_collaborator.py"]:::frontend
        click AC "https://github.com/zemariavg/notist-client/blob/main/actions/add_collaborator.py"
        RT["Retrieve Notes\nretrieve_notes.py"]:::frontend
        click RT "https://github.com/zemariavg/notist-client/blob/main/actions/retrieve_notes.py"
    end

    CLI -->|"dispatch"| CN
    CLI -->|"dispatch"| RN
    CLI -->|"dispatch"| EN
    CLI -->|"dispatch"| LN
    CLI -->|"dispatch"| BN
    CLI -->|"dispatch"| CI
    CLI -->|"dispatch"| AC
    CLI -->|"dispatch"| RT

    %% Cryptography Library
    subgraph "Cryptolib Core" 
        PROT["protect\nprotect.py"]:::core
        click PROT "https://github.com/zemariavg/notist-client/blob/main/cryptolib/protect.py"
        UNP["unprotect\nunprotect.py"]:::core
        click UNP "https://github.com/zemariavg/notist-client/blob/main/cryptolib/unprotect.py"
        CHK["integrity check\ncheck.py"]:::core
        click CHK "https://github.com/zemariavg/notist-client/blob/main/cryptolib/check.py"
        NOTI["notification/state\nnotist.py"]:::core
        click NOTI "https://github.com/zemariavg/notist-client/blob/main/cryptolib/notist.py"
    end

    subgraph "Cryptolib Utils"
        CRU["cryptoutils\ncryptoutils.py"]:::utils
        click CRU "https://github.com/zemariavg/notist-client/blob/main/cryptolib/utils/cryptoutils.py"
        CIF["file I/O\nfile.py"]:::utils
        click CIF "https://github.com/zemariavg/notist-client/blob/main/cryptolib/utils/file.py"
        NPAR["noteparser\nnoteparser.py"]:::utils
        click NPAR "https://github.com/zemariavg/notist-client/blob/main/cryptolib/utils/noteparser.py"
    end

    CN -->|"encrypt/decrypt"| PROT
    RN -->|"encrypt/decrypt"| UNP
    CI -->|"call check"| CHK
    CN -->|"notify"| NOTI

    CN -->|"low-level I/O"| CRU
    RN -->|"low-level I/O"| CIF
    EN -->|"parse notes"| NPAR

    %% General Utilities
    U["Note Utilities\nnoteutils.py"]:::utils
    click U "https://github.com/zemariavg/notist-client/blob/main/utils/noteutils.py"

    CN -->|"format/metadata"| U
    RN -->|"format/metadata"| U

    %% Filesystem
    subgraph "Filesystem"
        NOTES["Notes Folder\n(JSON)"]:::fs
        subgraph "Keys Folder"
            subgraph "user1_keys"
                U1P["priv.pem"]:::fs
                click U1P "https://github.com/zemariavg/notist-client/blob/main/keys/user1_keys/priv.pem"
                U1PUB["pub.pem"]:::fs
                click U1PUB "https://github.com/zemariavg/notist-client/blob/main/keys/user1_keys/pub.pem"
            end
            subgraph "user2_keys"
                U2P["priv.pem"]:::fs
                click U2P "https://github.com/zemariavg/notist-client/blob/main/keys/user2_keys/priv.pem"
                U2PUB["pub.pem"]:::fs
                click U2PUB "https://github.com/zemariavg/notist-client/blob/main/keys/user2_keys/pub.pem"
            end
            subgraph "user3_keys"
                U3P["priv.pem"]:::fs
                click U3P "https://github.com/zemariavg/notist-client/blob/main/keys/user3_keys/priv.pem"
                U3PUB["pub.pem"]:::fs
                click U3PUB "https://github.com/zemariavg/notist-client/blob/main/keys/user3_keys/pub.pem"
            end
            subgraph "user4_keys"
                U4P["priv.pem"]:::fs
                click U4P "https://github.com/zemariavg/notist-client/blob/main/keys/user4_keys/priv.pem"
                U4PUB["pub.pem"]:::fs
                click U4PUB "https://github.com/zemariavg/notist-client/blob/main/keys/user4_keys/pub.pem"
            end
        end
    end

    RN -->|"read/write"| NOTES
    CN -->|"read/write"| NOTES
    CRU -->|"load keys"| U1P
    CRU -->|"load keys"| U2P
    CRU -->|"load keys"| U3P
    CRU -->|"load keys"| U4P

    %% Tests
    subgraph "Cryptolib Tests"
        T1["tests.py"]:::test
        click T1 "https://github.com/zemariavg/notist-client/blob/main/cryptolib/test/tests.py"
        TK["test_keys/"]:::test
        click TK "https://github.com/zemariavg/notist-client/tree/main/cryptolib/test/test_keys/"
        TN["test_notes/"]:::test
        click TN "https://github.com/zemariavg/notist-client/tree/main/cryptolib/test/test_notes/"
    end

    %% Styles and Legend
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef utils fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef fs fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef test fill:#f0e68c,stroke:#333,stroke-width:1px

    %% Legend
    subgraph Legend
        L1["Rectangle = Component"]:::fs
        L2["Dashed = Config Read"]:::fs
        L3["Solid = Invocation/Data Flow"]:::fs
    end
```
