# fordcois/cryptography architecture

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

- Interactive diagram: https://gitdiagram.com/fordcois/cryptography
- Repository: https://github.com/fordcois/cryptography

## Overview

##### Main Components
- Data/Input:
- “cipher_texts” directory contains plaintext examples from literary works (e.g., texts from “A Tale of Two Cities”, “Moby Dick”, etc.) that serve as inputs for experimenting with ciphers.
- “whitelisted_words.txt” (present in both root and within lib) provides word lists for validation.
- Core Functionality (Prime Logic):
- Under “lib/encrypt_functions”: modules for cipher algorithms including Caesar, keyword cipher, and punctuation removal. These represent the encryption/decryption logic.
- “lib/validation_tools”: functions for checking accuracy and validating whether a decrypted solution is correct.
- Supporting Utilities:
- “utilities”: contains auxiliary classes and functions (e.g., a CipherSymbol object to track symbol likelihoods and a module to import text files).
- Documentation and Analysis:
- “documentation”: holds markdown files that document experiments and detailed frequency analyses, explaining the rationale behind frequency, bigraph, and pattern analysis.
- Testing:
- “tests”: contains unit tests for the encryption functions and validation tools (making sure each cipher method functions as expected).

##### Relationships and Interactions
- Data Flow:
- Input texts (from “cipher_texts” and via “utilities/txt_import.py”) are fed into the encryption functions.
- The encryption functions, which implement the cipher algorithms (from “lib/encrypt_functions”), process the text (removing punctuation, substitution through Caesar or keyword ciphers).
- The processed output is then passed to the validation tools (located in “lib/validation_tools”) to check decryption accuracy against the whitelisted words.
- Supporting Feedback Loop:
- The results from validation can be used to refine parameters, which is part of the learning and experiment cycle (documented in “documentation”).
- Testing and Continuous Integration:
- The “tests” module ensures that changes in encryption functions or validation logic do not break existing functionality.

##### Architectural Patterns & Principles
- Modular Design: Distinct modules for encryption, validation, and utilities promote separation of concerns.

##### Final Reminder to the Principal Software Engineer
- Labels are clear and unambiguous.
- Remember that the modular separation (for instance, separating encryption functions from validation tools) is crucial to both understand and potentially scale the experimental framework.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data/Input Layer
    subgraph "Data/Input"
        A["cipher_texts (Directory)"]:::data
        B["whitelisted_words.txt (Root)"]:::data
    end

    %% Supporting Utilities Layer
    subgraph "Supporting Utilities"
        E1["CipherSymbol_class.py"]:::utility
        E2["txt_import.py"]:::utility
    end

    %% Encryption Functions Layer
    subgraph "Encryption Functions"
        C1["caesar_cipher.py"]:::core
        C2["keyword_cipher.py"]:::core
        C3["remove_punctuation.py"]:::core
    end

    %% Validation Tools Layer
    subgraph "Validation Tools"
        D1["check_accuracy.py"]:::core
        D2["valid_solution.py"]:::core
        D3["whitelisted_words.txt (Lib)"]:::core
    end

    %% Documentation & Analysis Layer
    subgraph "Documentation & Analysis"
        F1["000_checking_results.md"]:::doc
        F2["001_Frequency_Analysis.md"]:::doc
    end

    %% Test Suite Layer
    subgraph "Test Suite"
        G1["test_caesar.py"]:::test
        G2["test_keyword_cipher.py"]:::test
        G3["test_remove_punctuation_and_normalise.py"]:::test
        G4["test_valid_solution.py"]:::test
    end

    %% Data Flow Connections
    A -->|"ImportText"| E2
    E2 -->|"ProcessText"| C1
    C1 -->|"Encrypt/Decrypt"| D1
    B -->|"WordList"| D3
    D1 -->|"ValidationResults"| F1

    %% Testing Connections
    G1 -->|"TestCaesar"| C1
    G2 -->|"TestKeyword"| C2
    G3 -->|"TestPunctuation"| C3
    G4 -->|"TestValidation"| D2

    %% Styling Classes
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px
    classDef utility fill:#FFFF99,stroke:#000,stroke-width:2px
    classDef doc fill:#D3D3D3,stroke:#000,stroke-width:2px
    classDef test fill:#FFA500,stroke:#000,stroke-width:2px

    %% Click Events
    click A "https://github.com/fordcois/cryptography/tree/main/cipher_texts/"
    click B "https://github.com/fordcois/cryptography/blob/main/whitelisted_words.txt"
    click C1 "https://github.com/fordcois/cryptography/blob/main/lib/encrypt_functions/caesar_cipher.py"
    click C2 "https://github.com/fordcois/cryptography/blob/main/lib/encrypt_functions/keyword_cipher.py"
    click C3 "https://github.com/fordcois/cryptography/blob/main/lib/encrypt_functions/remove_punctuation.py"
    click D1 "https://github.com/fordcois/cryptography/blob/main/lib/validation_tools/check_accuracy.py"
    click D2 "https://github.com/fordcois/cryptography/blob/main/lib/validation_tools/valid_solution.py"
    click D3 "https://github.com/fordcois/cryptography/blob/main/lib/validation_tools/whitelisted_words.txt"
    click E1 "https://github.com/fordcois/cryptography/blob/main/utilities/CipherSymbol_class.py"
    click E2 "https://github.com/fordcois/cryptography/blob/main/utilities/txt_import.py"
    click F1 "https://github.com/fordcois/cryptography/blob/main/documentation/000_checking_results.md"
    click F2 "https://github.com/fordcois/cryptography/blob/main/documentation/001_Frequency_Analysis.md"
    click G1 "https://github.com/fordcois/cryptography/blob/main/tests/test_caesar.py"
    click G2 "https://github.com/fordcois/cryptography/blob/main/tests/test_keyword_cipher.py"
    click G3 "https://github.com/fordcois/cryptography/blob/main/tests/test_remove_punctuation_and_normalise.py"
    click G4 "https://github.com/fordcois/cryptography/blob/main/tests/test_valid_solution.py"
```
