{"id":26442144,"url":"https://github.com/mawdesign/lyricsanctuary","last_synced_at":"2026-05-04T16:36:06.798Z","repository":{"id":281751916,"uuid":"946307587","full_name":"mawdesign/lyricSanctuary","owner":"mawdesign","description":"lyricSanctuary: A web application for managing and organizing song lyrics with detailed musical and contextual information, built with Python, CouchDB, and a hexagonal architecture.","archived":false,"fork":false,"pushed_at":"2025-03-18T03:03:21.000Z","size":15,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T03:33:01.214Z","etag":null,"topics":["cc-by-sa","couchdb","database","hexagonal-architecture","json-schema","lyrics-management","music-database","python","rest-api","web-application"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mawdesign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2025-03-10T23:56:23.000Z","updated_at":"2025-03-18T03:03:24.000Z","dependencies_parsed_at":"2025-03-11T01:19:40.255Z","dependency_job_id":"968b6d21-220b-4c0e-9cbe-762bbeee5a36","html_url":"https://github.com/mawdesign/lyricSanctuary","commit_stats":null,"previous_names":["mawdesign/lyricsanctuary"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawdesign%2FlyricSanctuary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawdesign%2FlyricSanctuary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawdesign%2FlyricSanctuary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mawdesign%2FlyricSanctuary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mawdesign","download_url":"https://codeload.github.com/mawdesign/lyricSanctuary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244198395,"owners_count":20414443,"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":["cc-by-sa","couchdb","database","hexagonal-architecture","json-schema","lyrics-management","music-database","python","rest-api","web-application"],"created_at":"2025-03-18T10:17:46.535Z","updated_at":"2026-05-04T16:36:06.781Z","avatar_url":"https://github.com/mawdesign.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=center\u003e\n   \u003cimg alt=\"lyricSanctuary\" src=\"/docs/assets/LS_logo-dark.svg\" /\u003e\u003cbr/\u003e\n\u003c/p\u003e\n\u003ch2 align=center\u003e\u003cem\u003eLyrics and Music. Sorted.\u003c/em\u003e\u003c/h2\u003e\n\n[![License](https://img.shields.io/badge/License-CC--BY--SA%204.0-lightgrey.svg)](LICENSE.md)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Google Gemini](https://img.shields.io/badge/Google%20Gemini-886FBF?logo=googlegemini\u0026logoColor=fff)](https://gemini.google.com)\n[![stability-wip](https://img.shields.io/badge/stability-wip-lightgrey.svg)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#work-in-progress)\n\n## Table of Contents\n\n* [Introduction](#introduction)\n* [Design Patterns](#design-patterns)\n* [Installation](#installation)\n* [References, Inspirations, and Acknowledgements](#references-inspirations-and-acknowledgements)\n* [AI Usage](#ai-usage)\n* [License](#license)\n\n## Introduction\n\nWelcome to **lyricSanctuary**, a web-based application designed to store, manage, and retrieve lyrics with associated musical and contextual information. This application is built with a focus on organization and extensibility, allowing users to store details such as song titles, authors, CCLI numbers, copyright information, detailed lyric breakdowns (verses, choruses, bridges, etc.), keys, associated documents (PDFs, MusicXML), songbook references, and Bible passages.\n\n**lyricSanctuary** uses a document-oriented database (CouchDB with Mango Query Server) to provide flexible data storage and retrieval, with a Python-based web UI and API. The application is designed to be scalable and maintainable, making it suitable for both personal use and collaborative projects.\n\n## Design Patterns\n\n**lyricSanctuary** is designed with the following architectural and design patterns in mind:\n\n* **Hexagonal Architecture (Ports and Adapters):**\n    * The application is structured into distinct layers: Domain, Application, and Infrastructure (Adapters).\n    * This separation allows for independent development and testing of each layer.\n    * Adapters provide interfaces to external systems (e.g., CouchDB, web UI, API), ensuring that the core application logic remains decoupled.\n* **Model-View-Controller (MVC) Principles:**\n    * While not a strict MVC implementation, the application adheres to similar principles:\n        * **Model:** The `lyricsRepository` and database represent the data model.\n        * **View:** The web UI and API handle the presentation of data.\n        * **Controller:** The `lyricsService` acts as a controller, coordinating interactions between the model and the view.\n* **Document-Oriented Database:**\n    * CouchDB with Mango Query Server is used to store data in JSON format, providing flexibility and scalability.\n    * Mango queries allow for powerful json based searches.\n* **Short GUIDs:**\n    * Each song is assigned a short guid for use in retreival, update, and deletion.\n\n## Installation\n\nThis application is designed to run on a LEMP (Linux, Nginx, Mango/CouchDB, Python) Stack on a server.\n\nBasic server setup is:\n\n  ```bash\n  sudo apt update\n  sudo apt install nginx ufw\n  sudo ufw allow 'Nginx HTTP'\n  sudo ufw allow 'Nginx HTTPS' # If you will use https\n  sudo ufw enable\n  ```\n\nFollow these steps to set up **lyricSanctuary** on your local machine:\n\n1.  **Prerequisites:**\n    * Python 3.8 or later\n    * CouchDB (with Mango Query Server enabled)\n    * Git\n\n2.  **Clone the Repository:**\n    ```bash\n    git clone https://github.com/mawdesign/lyricSanctuary\n    cd lyricSanctuary\n    ```\n\n3.  **Create a Virtual Environment (Recommended):**\n    ```bash\n    python -m venv venv\n    venv\\Scripts\\activate # On Windows\n    source venv/bin/activate # On macOS/Linux\n    ```\n\n4.  **Install Dependencies:**\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n5.  **Configure CouchDB:**\n    * Ensure that CouchDB is running and accessible.\n    * Update the application's configuration to point to your CouchDB instance.\n    * The application expects the COUCHDB_URL and COUCHDB_DATABASE to be set.\n\n       \u003cdetails\u003e\n       \u003csummary\u003eOn macOS...\u003c/summary\u003e\n\n       ```bash\n       launchctl setenv COUCHDB_URL 127.0.0.1\n       launchctl setenv COUCHDB_DATABASE lyricSanctuary\n       ```\n       \n       \u003c/details\u003e\n\n6.  **Run the Application:**\n    * Start the python web app using your selected python web framework.\n\n7.  **Access the Application:**\n    * Open your web browser and navigate to the appropriate URL.\n\n8. **Database Creation:**\n    * The database will be created on the first run, if it does not already exist.\n\n## References, Inspirations, and Acknowledgements\n\n* [Hexagonal architecture](https://dzone.com/articles/hexagonal-architecture-lyrics-app-example-java?edition=965104) for the idea to make a lyric store using hexagonal architecture.\n* [OpenSong](https://opensong.org/development/file-formats/) has been used as a basis for ensuring the schema for songs has all the necessary fields.\n* [BetterStack](https://betterstack.com/community/guides/logging/how-to-start-logging-with-python/) guides to logging and using json files.\n  \n## AI Usage\n\nThis project is an experiment with utilising AI as a coding companion, Google Gemini has been used to help write code and Gemini Code Assist has been used to review code.\n\n## License\n\nThis project is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. See the [LICENSE](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmawdesign%2Flyricsanctuary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmawdesign%2Flyricsanctuary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmawdesign%2Flyricsanctuary/lists"}