{"id":18185981,"url":"https://github.com/jjba23/wikimusic-api","last_synced_at":"2025-04-02T00:31:50.665Z","repository":{"id":255506401,"uuid":"851110077","full_name":"jjba23/wikimusic-api","owner":"jjba23","description":"https://codeberg.org/jjba23/wikimusic-api","archived":true,"fork":false,"pushed_at":"2024-11-28T21:03:53.000Z","size":82,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-03-10T12:57:28.245Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jjba23.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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-09-02T12:49:53.000Z","updated_at":"2024-12-01T19:36:57.000Z","dependencies_parsed_at":"2024-10-20T14:05:53.666Z","dependency_job_id":null,"html_url":"https://github.com/jjba23/wikimusic-api","commit_stats":null,"previous_names":["jjba23/wikimusic-api"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjba23%2Fwikimusic-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjba23%2Fwikimusic-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjba23%2Fwikimusic-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjba23%2Fwikimusic-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jjba23","download_url":"https://codeload.github.com/jjba23/wikimusic-api/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246735167,"owners_count":20825216,"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":["api","free","haskell","music","rest","servant","sqlite"],"created_at":"2024-11-02T23:04:16.930Z","updated_at":"2025-04-02T00:31:50.455Z","avatar_url":"https://github.com/jjba23.png","language":null,"funding_links":["https://www.buymeacoffee.com/jjbigorra"],"categories":[],"sub_categories":[],"readme":"#+title: WikiMusic API\n\nAPI and Persistence layer to SQLite for WikiMusic, the invite-only private knowledge sharing of music community.\n\n/WikiMusic/\n\n#+begin_html\n\u003cdiv\u003e\n\u003cimg src=\"https://img.shields.io/badge/Haskell-5D4F85?logo=haskell\u0026logoColor=fff\u0026style=plastic\" alt=\"Haskell\"/\u003e\n\u003cimg src=\"https://img.shields.io/badge/SQLite-4169E1?logo=sqlite\u0026logoColor=fff\u0026style=plastic\" alt=\"SQLite\"/\u003e\n\u003cimg src=\"https://img.shields.io/badge/NixOS-5277C3?logo=nixos\u0026logoColor=fff\u0026style=plastic\" alt=\"NixOS\"/\u003e\n\u003cimg src=\"https://img.shields.io/badge/GNU%20Emacs-7F5AB6?logo=gnuemacs\u0026logoColor=fff\u0026style=plastic\" alt=\"GNU Emacs\"/\u003e\n\u003c/div\u003e\n#+end_html\n\n\nWikiMusic as a software means an ingenious combination of a backend, a REST API, a database, and a user-interface to create a Content Management System (CMS) and a Gallery for music of all kinds, with educational intents.\n\nThis is 100% free software, licensed under the GNU General Public License v3 or later.\n[[https://www.gnu.org/licenses/gpl-3.0.en.html][Refer to the full license, on GNU's website]]\n\nThe WikiMusic project is an invite-only community, with the goal of knowledge sharing, and not for profit driven.\n\n[[https://www.buymeacoffee.com/jjbigorra][Please donate by clicking here]]. This helps us keep the underlying cloud infrastructure and Joe's work hours going strong.\n\nIn this Git repository you will find the source code behind WikiMusic's backend.\n\nTo see the living API spec of WikiMusic, also known as API definition, go to [[file:src/WikiMusic/Servant/ApiSpec.hs]]\n\n** Project structure\n\n~src/WikiMusic/~ harbours the Haskell code that makes the API work. Inside there you will find:\n- ~Console~ is a package with functionality related to logging to console / stdout.\n- ~Free~ is a package with free monadic definitions of the possible interactions with the WikiMusic system.\n- ~Interaction~ is a package with the implementation agnostic \"business logic\" of the WikiMusic system.\n- ~Model~ is a package with common data models to the entire system.\n- ~Persistence~ is a package with the Persistence implementation of several ~Command~ and ~Query~ interactions.\n- ~Smtp~ is a package that contains Smtp Mail related implementations.\n- ~Servant~ is a package that contains the API definition, routes and wiring of HTTP.\n- ~Boot.hs~ is the entry point to start this REST API.\n- ~Protolude.hs~ contains a custom tailor-made standard library (prelude) for WikiMusic, which helps developing.\n\n** Implementation details\n\nWikiMusic API is made using Haskell and free(er) monad techniques, along with great libraries made by the brilliant Haskell community. Some worthy mentions include servant, free-alacarte, wai, keuringsdienst, optics.\n\nUsing free(er) monads means that we can describe the business logic of certain layers at a very high abstraction level, and we are free to interpret this logic as we see fit, depending on the use case. This helps testing, decoupling, and maintaining code.\n\n** Installing and running\n\nThis Haskell project requires certain C / C++ libraries to run. Pay attention the the error messages at build time and install dependencies accordingly.\n\nWe recommend running WikiMusic API with the Nix package manager, and even better with NixOS, since this project has a close integrations for NixOS machines.\n\nOtherwise, on systems like Void Linux :\n#+begin_src\nsudo xbps-install zlib zlib-devel ncurses-libtinfo-devel\n#+end_src\n\nYou will also need a SQLite database to be accessible from WikiMusic API and running.\n\nWikiMusic will take care of the database schema migrations for you.\n\nThere are also example docker compose files ready to be used at the ~resources~ folder for your convenience.\n\n* User permission\n\nIn WikiMusic we have users of several kinds, with different privileges. See the table below for an understanding on what you can/cannot do depending on your rank.\n\nDemo user:\n\n| Resource | Create | Read | Update | Delete | Comment | Like/Dislike |\n|----------+--------+------+--------+--------+---------+--------------|\n| Song     | ❌     | ✅   | ❌     | ❌     | ✅      | ✅           |\n| Artist   | ❌     | ✅   | ❌     | ❌     | ✅      | ✅           |\n| Genre    | ❌     | ✅   | ❌     | ❌     | ✅      | ✅           |\n| User     | ❌     | ❌   | ❌     | ❌     | N/A     | N/A          |\n\nLow-rank user:\n\n| Resource | Create | Read | Update | Delete | Comment | Like/Dislike |\n|----------+--------+------+--------+--------+---------+--------------|\n| Song     | ✅     | ✅   | ✅     | ❌     | ✅      | ✅           |\n| Artist   | ✅     | ✅   | ✅     | ❌     | ✅      | ✅           |\n| Genre    | ✅     | ✅   | ✅     | ❌     | ✅      | ✅           |\n| User     | ❌     | ❌   | ❌     | ❌     | N/A     | N/A          |\n\nMaintainer user:\n\n| Resource | Create | Read | Update | Delete | Comment | Like/Dislike |\n|----------+--------+------+--------+--------+---------+--------------|\n| Song     | ✅     | ✅   | ✅     | ✅     | ✅      | ✅           |\n| Artist   | ✅     | ✅   | ✅     | ✅     | ✅      | ✅           |\n| Genre    | ✅     | ✅   | ✅     | ✅     | ✅      | ✅           |\n| User     | ✅     | ✅   | ✅     | ❌     | N/A     | N/A          |\n\nSuper-user: can do everyting to the system!\n\n* NixOS\n\nEnter a nice shell provided by flakes, by doing ~nix develop~. You can also do ~nix build~ to build the project with Nix.\n\nRun the API with for example: ~nix run . -- \"./resources/config/run-local.toml\"~ .\n\n\n** Bare metal\n\nIt can be needed, if you want to run bare metal without direnv, to do things like this sometimes in the ~cabal.project~ (find by ~find /nix -name \"zlib.h*\"~):\n\n#+begin_src nix\npackage zlib\n    extra-include-dirs: /nix/store/686lhcz4bwg3wk09pi1xxjgzbxv7ys5q-zlib-1.3-dev/include\n    extra-lib-dirs: /nix/store/4rx3vkkd91wkbhpflsplfga603cp1l1c-zlib-1.3/lib\n#+end_src\n\n* API documentation\n\nWhen running WikiMusic API, you can navigate to ~\u003curl where you serve it\u003e/swagger.json~ to get the OpenAPI spec for WikiMusic.\n\n\n* Example config file\n\nFor local runs you can take a look at [[file:resources/config/run-local.toml]].\n\n* Production environment diagram\n\n#+begin_src dot :file resources/images/production-env-diagram.png :exports results :mkdirp yes\n  digraph prodenv {\n  subgraph clusterA {\n  fontname=\"Inter,Helvetica,Arial,sans-serif\"\n  node [ shape=\"box\", fontname=\"Inter,Helvetica,Arial,sans-serif\" ]\n  edge [ fontname=\"Inter,Helvetica,Arial,sans-serif\", arrowhead=\"rnormal\", arrowtail=\"dot\" ]\n\n  I1 [ label=\"api.wikimusic.jointhefreeworld.org via HTTPS\" ]\n  I2 [ label=\"AWS Cloudfront\" ]\n  I3 [ label=\"AWS EC2 t3.small instance\\nrunning NixOS\" ]\n  I4 [ label=\"Haskell + Servant + SQLite\" ]\n  I5 [ label=\"GitLab CI/CD\" ]\n  I6 [ label=\"AWS SQS queue\" ]\n\n\n  I1 -\u003e I2;\n  I2 -\u003e I3;\n  I3 -\u003e I4;\n  I5 -\u003e I6;\n  I3 -\u003e I6;\n\n  }\n  }\n#+end_src\n\n#+RESULTS:\n[[file:resources/images/production-env-diagram.png]]\n\n\n* Project management\n\nFind below a list ideas and work being done on this project by all our contributors.\n\n** Work in progress\n*** WIP Finish cleaning persistence layer by using only Beam for all queries\n\n\n** Project backlog\n*** TODO Automated Cabal Hackage release in CI and version bumps\n*** TODO Recently viewed functionality\n*** TODO Add optional lyrics for song textfield\n*** TODO Clock and identifier generation as free monads, take things to a higher level\n*** TODO Create and optimize custom Prelude, and clean all files imports\n*** TODO Improve reusability in ~fromString . T.unpack $ x~\n*** TODO Liked items list view (liked songs, liked genres)\n\n*** TODO Create \"for profit\" version (premium offline pre-rendered) of WikiMusic, as app (read-only)\n*** TODO Ensure all data models are validated in requests\n*** TODO Use more non-empty types and sets if possible\n*** TODO Remove unused dependencies\n*** TODO Create black box tests for basic system functioning (with SQLite )\n****  Create SQLite assertion DSL for tests with Beam (check row exists)\n*** TODO Genre \u003c\u003e Song \u003c\u003e Artist relation\n*** TODO Drop SQL tables of user favourites, since opinions table will be used for it\n*** TODO Add forums \n*** TODO Validate and limit size and type of files being uploaded\n**** TODO GP5 support (song file upload)\n*** TODO extract mail monad, service, templates and views into its own microservices, communicate via grpc if possible, otherwise REST and ensure retries and good logging\n*** TODO Prometheus metrics and visualizations, use Grafana in Docker, also in production server\n*** TODO wikimusic marketing emails, asking for donation, recommending last added and last edited top 10 items\n*** TODO WikiMusic email about new website and its changelog, every commit automatic mail users?, new capabilities to all users marketing\n\n\n** Done\n*** DONE Migration to GitHub\nCLOSED: [2024-09-04 wo 22:05]\n*** DONE fix email, do not expose Smtp credentials on GitHub\nCLOSED: [2024-09-04 wo 17:23]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjba23%2Fwikimusic-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjjba23%2Fwikimusic-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjba23%2Fwikimusic-api/lists"}