{"id":26901883,"url":"https://github.com/bxavaby/vault","last_synced_at":"2025-04-01T09:08:40.771Z","repository":{"id":266140523,"uuid":"897445425","full_name":"bxavaby/vault","owner":"bxavaby","description":"Exercises, Adventures, Final Software Engineering Project!","archived":false,"fork":false,"pushed_at":"2025-03-28T10:52:51.000Z","size":10034,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T11:37:29.203Z","etag":null,"topics":["json-data","literature","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bxavaby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-02T16:36:07.000Z","updated_at":"2025-03-28T10:52:54.000Z","dependencies_parsed_at":"2025-03-28T11:41:06.479Z","dependency_job_id":null,"html_url":"https://github.com/bxavaby/vault","commit_stats":null,"previous_names":["bxavaby/vault"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxavaby%2Fvault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxavaby%2Fvault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxavaby%2Fvault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxavaby%2Fvault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bxavaby","download_url":"https://codeload.github.com/bxavaby/vault/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246612485,"owners_count":20805355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-data","literature","python","python3"],"created_at":"2025-04-01T09:08:40.222Z","updated_at":"2025-04-01T09:08:40.757Z","avatar_url":"https://github.com/bxavaby.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Verse Vault**\n\nA private library for storing and exploring a collection of short texts, poems, apophthegms, and other literary pieces. The program provides a simple and interactive way to browse, fetch, and manage a library of texts.\n\n*— B. F.*\n\n---\n\n## **Table of Contents**\n\n- [Project Checklist](#project-checklist)\n- [Demo](#demo)\n- [Exemplary Screenshots](#exemplary-screenshots)\n- [Current Status](#current-status)\n- [Project Structure](#project-structure)\n- [Features](#features)\n- [Installation and Usage](#installation-and-usage)\n- [Customization Guide](#customization-guide)\n- [Acknowledgments](#acknowledgments)\n\n---\n\n## Project Checklist\n\n### 1. Use and Understand Git\n\n- All project updates are tracked and committed using Git.\n\n| **Command**               | **Used to...** |\n|---------------------------|---------------|\n| `git init`               | Start version control for the project. |\n| `git add .`              | Stage changes before making a commit. |\n| `git commit -m \"description\"`    | Commit the staged changes with a description. |\n| `git push origin master`   | Push committed changes to the remote repository. |\n| `git pull origin master`   | Fetch and merge the latest updates from the remote repository. |\n\nFor reference, these commands have been applied in multiple commits across the project:  \n\n🔗 **[GitHub Commit History](https://github.com/bxavaby/vault/commits/master)**\n\n---\n\n### 2. UML Diagrams\n\nTo document the architecture and behavior of *Verse Vault*, I have created the following **diagrams**:\n\n#### 1️⃣ Use-Case Diagram\nThe **Use-Case Diagram** visualizes how users interact with the system, showcasing different features available in the CLI.\n\n📌\n\n![Use-Case Diagram](media/use_case_diagram.png)\n\n- The **User** interacts with the CLI interface.\n- The user can perform actions such as:\n  - **Browsing** the library of texts.\n  - **Fetching** a random entry.\n  - **Searching** for specific texts by title or author.\n  - **Adding** new texts to the collection.\n  - **Favoriting** entries for later access.\n\n\n#### 2️⃣ Component Diagram\nThe **Component Diagram** represents the structural organization of the program, showing how different components communicate.\n\n📌\n\n![Component Diagram](media/component_diagram.png)\n\n- The **CLI Interface** serves as the user’s access point.\n- The **Library (JSON Storage)** holds text data.\n- **Utility Functions** provide helper methods for various operations.\n- **Display Manager** formats terminal output for readability.\n- **Data Manager** handles reading and writing to the storage.\n\n\n#### 3️⃣ Activity Diagram\nThe **Activity Diagram** illustrates the sequence of actions when a user fetches an entry.\n\n📌 \n\n![Activity Diagram](media/activity_diagram.png)\n\n- The process starts with the user selecting the *Browse your vault* option from the menu, followed by the category *Authors* or *Genres*.\n- The user decides between:\n  - **Fetching a random entry**.\n  - **Searching for a specific entry, by listing them all**.\n- The system retrieves the selected text and **displays it**.\n- The process ends when the entry is shown and the user hits **ENTER**.\n\n---\n\n### 3. Requirements\n\n#### Currently:\n\n![Trello (Simple)](media/trello_requirements.png)\n\n- [Link to Workspace](https://trello.com/invite/b/678fed2adab3041ec224dd07/ATTI4a251d1916f5f228df66c26d746aff325DBA7BE5/verse-vault)\n\n![Jira (Professional)](media/jira_requirements.png)\n\n---\n\n### 4. Analysis\n\n- Problem Definition\n- Target Audience\n- Unique Selling Proposition (USP)\n- Competitor Analysis\n- Core Features\n- Monetization Strategy\n- Technical Feasibility\n- User Experience (UX) Design\n- Data Privacy and Security\n- Scalability\n- Market Validation\n- Development Timeline\n- Risks and Challenges\n- Innovation Potential\n- Future Expansion\n\n[The Detailed Version](media/analysis.pdf)\n\n---\n\n### 5. Domain-Driven Design\n\n#### 🔎 **A) Event-Storming: Discovering Domains**\nTo define the functional areas of **Verse Vault**, I conducted **Event-Storming**, ensuring the project remains modular and extensible. The primary objective of this tool is to **help users store, explore, and manage a literary collection interactively**.\n\n#### **Identified Domains**\n\n| **Domain**                     | **Description**                                         | **Type** |\n|---------------------------------|---------------------------------------------------------|----------|\n| **Vault \u0026 Content Management**  | Stores and organizes short texts, poems, and quotes   | **Core** |\n| **Discovery \u0026 Retrieval**       | Allows users to search, fetch, and randomize entries  | **Core** |\n| **User Customization**          | Enables users to modify the database, add/edit texts  | Supporting |\n| **Styling \u0026 Display**           | Formats terminal output for readability               | Supporting |\n| **CLI \u0026 Interactive Commands**  | Handles user interactions via command-line interface  | **Core** |\n| **Favorites \u0026 Personalization** | Lets users mark preferred texts for quick access     | Supporting |\n\n\n#### **B) Core Domain Chart**\nBased on an event-storming process, the [chart](media/core_domain_chart.odg) found in [media](media/) highlights **core** domains.\n\n- **CLI \u0026 Interactive Input** serves as the main user interface.\n- **Vault \u0026 Management** handles text storage and retrieval.\n- **Discovery \u0026 Fetch** helps users explore the content.\n- **Styling \u0026 Display** ensure readable output.\n- **Personalization \u0026 Customization** enhance the user experience.\n\n---\n\n### 6. Metrics\n\nTo ensure **high performance, maintainability, and code quality**, Verse Vault was analyzed using **Flake8 and additional metrics**.\n\n#### 1️⃣ **Flake8 Code Quality Metrics**\nI ran a **Flake8 analysis**, focusing on:\n- **Unused Imports** (`F401`): Identifies unnecessary imports that can be removed to optimize performance.\n- **Trailing Whitespace \u0026 Blank Lines** (`W291`, `W293`, `W391`): Minor stylistic issues that were cleaned up.\n- **Indentation Issues** (`E111`, `E117`): Ensured all indentation is consistent and follows PEP-8 guidelines.\n- **Blank Line Formatting** (`E302`, `E305`, `E303`): Adjusted blank lines for readability and structure.\n\n📌 **Flake8 Report Before Fixes**:  \n![Flake8 Report Before](media/flake8_before.png)  \n\n📌 **Flake8 Report After Fixes**:  \n![Flake8 Report After](media/flake8_after.png)  \n\n#### 2️⃣ **Testing with Pytest**\nPytest focused on:\n- `--cov=utils` → Measures coverage for **utility functions**.  \n- `--cov=library` → Measures coverage for **JSON-based text storage**.  \n- `--cov-report=term` → Displays **coverage summary** in the terminal.  \n- `--cov-report=html` → Generates an **HTML report** with detailed results.  \n\n📌 **Pytest Report**:  \n![Report](media/pytest.png)  \n\n*Still a long way from the 80% goal, but the tested sections are most vital.*\n\n#### 📝 **Findings**:\n- **Removed unused imports**, to improve clarity.\n- **Fixed all whitespace and indentation errors**, to ensure a clean structure.\n\n---\n\n### 7. Clean Code Development (CCD)\n\n### **A) 5 Points of Clean Code in Verse Vault**\nHere are five improvements made to the project that contribute to **clean code principles**:\n\n#### 1️⃣ Meaningful Function \u0026 Variable Names  \n\nInstead of generic names like `data_func()`, the project uses **clear, self-explanatory names** like:\n\n```python\ndef load_library(text_type):\n    \"\"\"Load a JSON library file based on text type.\"\"\"\n```\n\n**Why?**  \n\n- Increases readability.  \n- Makes the code self-documenting.  \n- Reduces the need for unnecessary comments.  \n\n#### 2️⃣ Modular Structure (Separation of Concerns)  \n\nThe codebase follows **Single Responsibility Principle (SRP)** by splitting functionalities into separate modules:  \n\n- `display.py` → Handles UI and formatting.  \n- `fetcher.py` → Manages data retrieval.  \n- `data_manager.py` → Loads and saves JSON data.  \n\n**Why?**  \n\n- Easier maintenance.  \n- Better scalability.  \n- Clearer structure, making debugging more efficient.  \n\n#### 3️⃣ Consistent Formatting \u0026 PEP-8 Compliance  \n\nCode is formatted using **Flake8** to enforce consistent indentation, spacing, and line length.  \n\n**Example:**  \n\n```python\ndef display_menu():\n    menu_items = [\n        \"1. Browse your vault\",\n        \"2. Random poem\",\n        \"3. Random excerpt\",\n        \"4. Fill up your vault!\",\n        \"5. Show favourites \u003c3\",\n        \"6. Exit...\"\n    ]\n    menu_items.sort()\n```\n\n**Why?**  \n\n- Ensures clean, easy-to-read, and maintainable code. \n- Avoids style inconsistencies in the project.  \n\n#### 4️⃣ Error Handling \u0026 Exception Safety\n\nFunctions gracefully handle missing files instead of crashing.  \n\n**Example:**  \n\n```python\ndef load_library(text_type):\n    if text_type not in file_map:\n        raise ValueError(f\"Invalid text type '{text_type}' provided.\")\n```\n\n**Why?**  \n\n- Prevents unexpected crashes. \n- Ensures the program handles errors smoothly.\n- Improves user experience.\n\n#### 5️⃣ Test Coverage for Key Functions  \n\nImplemented **pytest** tests to ensure functions work as expected.  \nUsed **mock tests \u0026 coverage tracking** to verify code execution.  \n\n**Example:**  \n\n```python\ndef test_load_library():\n    data = load_library(\"Poem\")\n    assert isinstance(data, list)  # Ensures it returns a list\n```\n\n**Why?**  \n\n- Reduces the risk of bugs. \n- Ensures that core functions are working.\n- Helps achieve higher test coverage.\n\n### 📄 B) Clean Code Cheat Sheet  \n\nFor a more detailed reference on Clean Code principles, check out the **PDF cheat sheet**:  \n\n📥 **[Clean Code Cheat Sheet](media/cleancode.pdf)**  \n\n---\n\n#### 8. Refractoring\n\nThis section demonstrates two refactoring examples taken from the [refractoring.py](se-tasks/refractoring.py) script.\n\nEach example includes:  \n✔ The **original code**.  \n✔ The **refactored version**.  \n✔ An **explanation of improvements**.\n\n#### **1️⃣ Currency Conversion**\n🔴 **Original Code**\n```python\ndef convert_to_euro(amount_in_dollars):\n    dollar_to_euro_rate = 0.85\n    return amount_in_dollars * dollar_to_euro_rate\n\ndef demo_refact(money_net): \n    tax_rate = 0.3\n    money_after_tax = money_net * (1 - tax_rate)\n\n    money_in_euro = convert_to_euro(money_after_tax)\n\n    return money_in_euro\n\nnet_income = 1\nmoney_in_euro = demo_refact(net_income)\nprint(f\"\\nMoney in $ before tax: {net_income}\")\nprint(f\"\\nMoney in Euro after tax: {money_in_euro:.2f}\")\n```\n\n✅ **Refactored Code**\n```python\ndef convert_currency(amount, rate=0.85):\n    return amount * rate\n\ndef apply_tax(income, tax_rate=0.3):\n    return income * (1 - tax_rate)\n\ndef process_conversion(money_net, tax_rate=0.3, conversion_rate=0.85):\n    net_after_tax = apply_tax(money_net, tax_rate)\n    money_in_euro = convert_currency(net_after_tax, conversion_rate)\n    return money_in_euro\n\nnet_income = 1\nmoney_in_euro = process_conversion(net_income)\n\nprint(f\"\\nMoney in $ before tax: {net_income}\")\nprint(f\"\\nMoney in Euro after tax: {money_in_euro:.2f}\")\n```\n\n### What Changed \u0026 Why?\n#### ✅ Encapsulated logic into reusable functions:\n- ```convert_currency()``` allows for dynamic currency conversions.\n- ```apply_tax()``` separates the tax logic from the conversion.\n- ```process_conversion()``` applies both tax and currency conversion in one step.\n#### ✅ Improved Readability \u0026 Maintainability:\n- Functions now have clear responsibilities.\n- Easier to update tax rates or conversion rates if needed.\n#### ✅ Increased Code Reusability:\n- This approach supports multiple currencies and different tax rates in the future.\n\n#### **2️⃣ Print Statements \u0026 Logging**\n🔴 **Original Code**\n```python\nprint(f\"\\nMoney in $ before tax: {net_income}\")\nprint(f\"\\nMoney in Euro after tax: {money_in_euro:.2f}\")\n```\n\n✅ **Refactored Code**\n```python\nimport logging\n\nlogging.basicConfig(level=logging.INFO, format=\"%(message)s\")\n\ndef display_conversion_results(original, converted, currency=\"EUR\"):\n    logging.info(f\"\\nMoney before tax: ${original:.2f}\")\n    logging.info(f\"Money after tax in {currency}: €{converted:.2f}\")\n\nnet_income = 1\nmoney_in_euro = process_conversion(net_income)\n\ndisplay_conversion_results(net_income, money_in_euro)\n```\n\n### What Changed \u0026 Why?\n#### ✅ Replaced print statements with *logging*:\n- Logs are structured and easier to debug.\n- Can be redirected to log files or debugging tools.\n#### ✅ Encapsulated display logic into a function:\n- ```display_conversion_results()``` allows formatted logging.\n- Easier to modify later for different currencies.\n#### ✅ Professional Output Formatting:\n- Allows for cleaner logs and better readability.\n\n---\n\n#### 9. Build Management\n\nVerse Vault integrates a **Makefile-based build system** and **Sphinx for documentation** to automate testing and generate documentation.\n\n### 🛠 **Using the Makefile**\nA [`Makefile`](verse-vault/Makefile) is used to automate project tasks such as installing dependencies, running tests, generating code coverage, and building documentation.\n\n![Content in Makefile](media/makefile.png)\n\n### **Available Makefile Commands**\nRun these commands from the **project root directory**:\n\n| Command           | Description |\n|------------------|-------------|\n| `make lint`      | Run Flake8 linting to check for style errors. |\n| `make test`      | Run all tests with `pytest`. |\n| `make coverage`  | Generate a test coverage report. |\n| `make docs`      | Build project documentation using **Sphinx**. |\n| `make clean`     | Remove temporary files and caches. |\n\n### **Usage**\n```bash\n# Install all dependencies\nmake install\n\n# Run tests\nmake test\n\n# Generate test coverage report\nmake coverage\n\n# Build Sphinx documentation\nmake docs\n```\n\n### 🛠 **Sphinx for Documentation**\nThe [documentation](verse-vault/docs/build/html/index.html) was generated by Sphinx, which is a powerful tool for automating and managing documentation.\n\nWhat you will find in index.html:\n\n![First Sphinx Generation](media/sphinx_doc.png)\n\n### **Building**\nAfter running ```make docs```, the HTML documentation is available in:\n\n```bash\ndocs/build/html/index.html\n```\n\n### **To open it:**\n\n```bash\nxdg-open docs/build/html/index.html  # Linux\nopen docs/build/html/index.html      # macOS\nstart docs/build/html/index.html     # Windows\n```\n\n---\n\n#### 10. Continuous Delivery\n\nThe project integrates **GitHub Actions** to automate testing and documentation.  \nThe CI/CD pipeline ensures that every change to the repository is **automatically tested and validated** before deployment.\n\n### **CI/CD Workflow**  \n\nThe workflow is triggered on:\n- **Every push** to the `master` branch.  \n- **Every pull request** targeting `master`.  \n\n### **GitHub Actions Workflow Config**  \n\nThe **GitHub Actions workflow file** is located in:  \n```plaintext\n.github/workflows/ci.yml\n```\n\n### **The Contents of ci.yml:**\n\n![ciyml](media/ciyml.png)\n\n---\n\n#### 11. Unit Tests\n\nIncorporated **unit tests** within the codebase to improve **stability and maintainability**.  \n\n### Data Management Tests (`test_data_manager.py`)\n- *Load Empty Library*: Ensures that attempting to load a non-existent JSON file returns an empty list.\n- *Save and Load Data*: Verifies that data can be successfully saved to a JSON file and retrieved without corruption.\n\n### Display Tests (`test_display.py`)\n- *Ornament Formatting*: Checks that the terminal ornamentation function returns correctly formatted ASCII text.\n\n### Fetching Logic Tests (`test_fetcher.py`)\n- *Fetch by Title*: Ensures that a literary entry can be retrieved correctly based on title.\n- *Mocked Data Retrieval*: Validates that fetching functions work correctly using mock JSON data.\n\n---\n\n#### 12. IDE\nBefore I provide a list of all the code editors/IDE's + favourite shortcuts I have used while working on *Verse Vault*, I must clarify that **Micro** was my top pick most of the times, **VS Code** was used only when I felt the need to use **Copilot**, which I talk about in the next task, and as for **Neovim**, it was sort of experimental, but a great learning experience.\n\n- **Favorite Shortcuts**:\n\n  - **Micro**:\n    - `Ctrl+S` → Save file\n    - `Ctrl+Q` → Quit editor\n    - `Ctrl+E` → Command mode\n  - **Neovim**:\n    - `:w` → Save file\n    - `:q` → Quit editor\n    - `dd` → Delete line\n    - `Shift + :` → Command mode\n  - **VS Code**:\n    - `Ctrl+F` → Find text\n    - `Ctrl+Shift+P` → Command Palette\n    - `Alt+Shift+F` → Format document\n\n---\n\n#### 13. AI Coding\n\n- **AI Integration**:\n  - Copilot was set up inside VS Code for prompt code assistance and debugging. I had already configured it through GitHub, by connecting it to VS Code and installing the plug-in.\n  - [Fabric Framework](https://github.com/danielmiessler/fabric):  \n      Used it for its sleek and simple solution to leverage LLMs directly from the command line, enhancing workflow efficiency and allowing for swift experimentation.\n\n### The image below illustrates the use of **Fabric** in the CLI:\n\n![Understanding Sphinx with AI](media/fabric_example.png)\n\n---\n\n#### 14. Functional Programming\n\n- only final data structures\n- (mostly) side-effect-free functions\n- the use of higher-order functions\n- functions as parameters and return values\n- use closures / anonymous functions\n\n## Examples:\n\n### Using Tuples Instead of Lists\n```python\ndef get_supported_text_types():\n    return (\"Poem\", \"Short Story\", \"Apophthegm\", \"Other\")\n```\n\nTuples are immutable and therefore prevent accidental modifications.\n\n### Avoiding Mutable Defaults\n```python\ndef fetch_favourites(library=None):\n    if library is None:\n        library = load_all_libraries()\n    return tuple(entry for entry in library if entry.get(\"favourite\") == \"yes\")\n```\n\nPrevents accidental mutations by returning a new tuple.\n\n### Side-Effect-Free String Formatting\n```python\ndef format_title(title):\n    return title.strip().title()\n```\n\nDoes not modify the original title, it just returns a formatted version of it. \nPresent only in the README, since it is not needed in the program.\n\n### Applying Formatting to Multiple Entries\n```python\ndef apply_to_entries(entries, transform_function):\n    return [transform_function(entry) for entry in entries]\n\n# example\nformatted_entries = apply_to_entries(library, format_title)\n```\n\nAllows flexible processing of text entries.\n\n### Returning Functions for Dynamic Formatting\n```python\ndef get_formatter(style):\n    if style == \"uppercase\":\n        return str.upper\n    elif style == \"lowercase\":\n        return str.lower\n    return str.title\n\nformatter = get_formatter(\"uppercase\")\nprint(formatter(\"hello world\"))\n```\nReturns another function dynamically.\n\n### Closure with State\n```python\ndef counter():\n    count = 0\n    def increment():\n        nonlocal count\n        count += 1\n        return count\n    return increment\n\ncount_up = counter()\nprint(count_up()) \nprint(count_up())\n```\n\nThe ``increment()`` function remembers count (closure).\n\n### Lambda Function for Sorting\n```python\nsorted_entries = sorted(library, key=lambda x: x[\"title\"])\n```\n\nUses a lambda function to define a sorting key in a single line.\n\n---\n\n## **Demo**\n![Verse Vault Demo](media/verse.gif)  \n*Above: A brief walkthrough of the core features.*\n\n---\n\n## **Exemplary Screenshots**\n\n### **Add Entry Menu**\n![Entry Menu Screenshot](media/addnew.png)  \n*Above: Sub-menu with types of entry.*\n\n### **Browsing**\n![Browsing Texts Screenshot](media/browse.png)  \n*Above: Sub-menu with types of search.*\n\n### **Favourites List**\n![Favourites Screenshot](media/favs.png)  \n*Above: List of preferred titles.*\n\n---\n\n## **Current Status**\n### December 2, 2024:\n- Basic functionality is implemented, including:\n  - Text browsing and randomization features.\n  - Modular utilities for managing data, display, and fetching.\n  \n- The database is structured using JSON files stored in the `library/` directory.\n\n- Git is used for version control with the following commands:\n  - `git init`, `git clone`, `git add`, `git commit`, `git push`, `git pull`, `git status`, `git log`.\n\n- PyCache files have been ignored using `.gitignore`.\n\n### December 20, 2024:\n- Every functionality is implemented, including:\n  - Favoriting, filtered browsing and optimized randomization features.\n  - Clean, flask8-approved, and modular utils.\n  - Hand-picked palette and polished ornamentation.\n\n---\n\n## **Project Structure**\n```plaintext\n.\n├── README.md\n└── verse-vault\n    ├── assets\n    │   └── logo.txt\n    ├── library\n    │   ├── apophthegm.json     # apophthegms\n    │   ├── other_texts.json    # miscellaneous\n    │   ├── poems.json          # poems\n    │   └── short_stories.json  # short stories\n    ├── main.py                 # entry point\n    ├── requirements.txt        # dependencies\n    └── utils\n        ├── data_manager.py     # handles loading and saving JSON files\n        ├── display.py          # handles terminal display and styling\n        ├── fetcher.py          # internal fetcher\n        └── __init__.py         # module initializer\n```\n\n---\n\n## **Features**\n- **Browse**: Navigate through your library by category (poems, apophthegms, short stories, others, favorited).\n- **Fetch**: Fetch random entries or search by author/genre/title.\n- **Customizable**: Easily add new texts or modify the existing content.\n- **Minimalist Design**: Simple and clean display focused on readability.\n\n---\n\n## **Installation and Usage**\n\n#### **Prerequisites**\n- Python 3.8 or later\n- Virtual environment (recommended)\n\n#### **Steps to Run**\n1. **Clone the Repository**:\n\n   ```bash\n   git clone https://github.com/bxavaby/verse-vault.git\n   cd verse-vault\n   ```\n   \n2. **Install Dependencies**:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n   \n3. **Run the Program**:\n\n   ```bash\n   python main.py\n   ```\n   \n---\n\n## **Customization Guide**\n\n### **1. Update the Logo**\nPersonalize the ASCII art logo displayed on startup.\n\n- **Create Your Logo**:\n  Use [Text to ASCII](https://patorjk.com/software/taag/) to create a custom logo.\n- **Replace the Logo File**:\n  Update the `logo.txt` in the `assets/` directory.\n- **Preview**:\n  Run the program to see your new logo.\n\n### **2. Add New Categories**\nTweak your library by:\n\n- **Deleting unwanted entries (manually)** in the `library/` directory \u003e\u003e select the JSON file \u003e\u003e delete any or all entries manually.\n- **Adding new enties (manually)** in the `library/` directory \u003e\u003e select the JSON file \u003e\u003e add new entries manually.\n- **Adding new entries (automatically)** run the program \u003e\u003e select option 4 (\"Fill up your vault!\") \u003e\u003e add the content interactively \u003e\u003e the program appends the new entry to the selected JSON automatically.\n\n### **3. Change Display Colors**\n\n- **Customizing the terminal colors** modify the COLOR_SCHEMES across all files using them (not optimal, will update in the future).\n\n### **4. Customize Favorites**\n\n- **Picking your preferred titles (manually)** in the `library/` directory \u003e\u003e select the JSON file \u003e\u003e edit the value directly (yes/no).\n- **Picking your preferred titles (automatically)** when adding a new entry (option 4), the program requests a boolean value (yes/no).\n\n---\n\n## **Acknowledgments**\nThis project is inspired by a deep appreciation for literature, philosophy and the desire to create a personal, private library of short-form texts.\n\n\n[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)\n[![Platform](https://img.shields.io/badge/Platform-Terminal-lightgrey?style=flat-square)](#)\n[![Contributions](https://img.shields.io/badge/Contributions-Welcome-orange?style=flat-square)](CONTRIBUTING.md)\n[![GitHub issues](https://img.shields.io/github/issues/bxavaby/vault?style=flat-square)](https://github.com/bxavaby/vault/issues)\n[![GitHub forks](https://img.shields.io/github/forks/bxavaby/vault?style=flat-square)](https://github.com/bxavaby/vault/network)\n[![GitHub stars](https://img.shields.io/github/stars/bxavaby/vault?style=flat-square)](https://github.com/bxavaby/vault/stargazers)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxavaby%2Fvault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbxavaby%2Fvault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxavaby%2Fvault/lists"}