feat: updated readmes

README.md

@@ -1,2 +1,37 @@
 # go-music-player
 
+## Backend
+
+This manages the music library database, serves requests and handles client connections.
+
+For more info, see the [readme](music-player/README.md).
+
+## Frontend clients
+
+Each frontend implements the APIs provided by the backend. Their job is to play music, or control the master client. The following clients are implemented:
+
+- [gmus-web](./gmus/README.md) - web client
+
+## Architecture
+
+### Database
+
+This is PostgreSQL. It is responsible for storing the music files and their metadata.
+
+### PubSub
+
+This is implemented in Go using Redis. It is responsible for coordinating state between clients. Note that the only state which is stored on the backend is the list of clients currently connected.
+
+### API
+
+This is an HTTP API written in Go. It is responsible for implementing the PubSub, as well as serving data to the clients. The API may be running in multiple redundant containers.
+
+### Scanner
+
+This keeps the database up-to-date, based on a directory containing music files.
+
+### Clients
+
+Each client connects to the API. One client is "master", while all others are "slave". Master is responsible for playing the music, and keeping other clients up-to-date through the socket.
+
+There is no authentication - all clients are trusted equally. Clients may take over master status whenever they want. Master must obey this instruction. Clients are responsible for providing unique names when connecting.

gmus/README.md

@@ -1,6 +1,6 @@
-# gmus client
+# gmus-web client
 
-This is a frontend web app for use with the gmus server.
+This is a frontend web app for use with the go-music-player server.
 
 ## Scripts
 
@@ -15,3 +15,29 @@ Runs tests
 ### `yarn build`
 
 Builds app
+
+## Architecture
+
+### Global app
+
+This is the main part of the app. It is responsible for handling:
+
+- Global state such as which song is playing, and the current time
+- Connections to the API, through a websocket
+- Sharing state with other clients, and responding to updates from the API
+- Playing music, through an HTML <audio> element
+
+### UI
+
+This is the part of the app which implements user interaction. It is responsible for handling:
+
+- User input, to decide which actions to take
+- Display, to let the user know the state of things
+
+UIs follow a common model and are built into separate bundles, then [lazily loaded](./src/components/ui/index.ts).
+
+The following UIs are implemented:
+
+#### cmus
+
+This is based heavily on the cmus ncurses-based music player, and is essentially a web-based client with vim-like bindings for navigation.

music-player/README.md

@@ -1,4 +1,4 @@
-# music-scanner
+# go-music-player backend
 
 This is the backend part of the music player, written in Golang.
 
@@ -39,3 +39,35 @@ This is intended to be run as a scheduled job. It will scan a directory and add
 **Usage**
 
 `bin/scan`
+
+### REST/WebSocket API
+
+**Usage**
+
+`bin/server`
+
+This is an HTTP server running the following endpoints:
+
+## GET /stream?songid=<id>
+
+Streams an audio file based on the `songid` value in the query string.
+
+##  GET /pubsub
+
+Handles long-running client connections, initiating a websocket.
+
+## GET /artists
+
+Fetches all artists, and outputs them in JSON format.
+
+## GET /albums?artist=<artist>
+
+Fetches albums for a particular artist, and outputs them in JSON format.
+
+## GET /songs?artist=<artist>
+
+Fetches songs for a particular artist, and outputs them in JSON format.
+
+## GET /song-info?id=<id>
+
+Fetches info for a particular song, based on its ID, and outputs it in JSON format.