start meaningful README

README.md

@@ -1,8 +1,42 @@
 # mydiary
 
-2021 Jason Portenoy
+Maintain a personal diary, with assistance from automated daily journal entries generated from connected third-party APIs.
 
-## .env file
+## What is this?
+
+Maintaining a personal diary has [numerous benefits](https://lifehacker.com/why-you-should-keep-a-journal-and-how-to-start-yours-1547057185), but I haven't always been able to keep up the habit. I started this project as a way to generate automated outlines for daily journal entries from different sources, such as Google Calendar for the events of a day, and Spotify for the songs I listened to on a day. I can add my own writing on top of these automated diary entries, but even when I don't, I have some information about the day that I can go back to later.
+
+Additionally, this project is an excuse to learn and tinker with a wide variety of digital tools and APIs. I've learned a great deal about developing full-stack software, gaining experience with [SQLModel](https://sqlmodel.tiangolo.com/), [SQLAlchemy](https://www.sqlalchemy.org/), [FastAPI](https://fastapi.tiangolo.com/), [React](https://react.dev/), [Vue](https://vuejs.org/), and [Docker Compose](https://docs.docker.com/compose/), just to name a few. Some of these skills have been helpful professionally, but they've all been pretty fun to learn.
+
+Finally, this project is also the home for some of my own [Personal Information](https://en.wikipedia.org/wiki/Personal_information_management). I like to play guitar and sing, for instance, so I use this mydiary database to keep track of all the songs I know how to perform, as well as songs I want to learn.
+
+## What this isn't
+
+This is **not** a plug-and-play solution for starting or maintaining a diary. The primary purpose of the project for me is to tinker, and certainly not to make things easy. There are surely many existing journaling solutions out there, but I made this with a focus on wrangling a bunch of open-source and customizable technologies together with third-party APIs to create something clunky, fun, and bespoke to me. If this resonates with you, maybe you could use what I've done as an example to do something similar for yourself! Just don't expect something easy and working out of box.
+
+## Diary entries (MyDiaryDay)
+
+Each daily dairy entry has a few different sections, which are connected to other apps and services. The entries are generated as [Markdown](https://en.wikipedia.org/wiki/Markdown) (.md) files, with these sections outlined and filled in as much as possible.
+
+### Words
+
+This is the text part of the diary entry, which I write after the rest as been generated (if I'm not being lazy or otherwise neglecting it). I use [Joplin](https://joplinapp.org/) to write and maintain the full entries. Joplin is a Markdown-based note-taking app—sort of an open-source version of Evernote. I sync all of my Joplin notes using the open-source [Nextcloud](https://nextcloud.com/) software.
+
+### Google Calendar events
+
+Mydiary connects to my personal Google Calendar and fills in all the events for a day. I often use my calendar as a lightweight journaling solution, even backfilling things I did in the last few days when I have a few minutes to do so.
+
+### Pocket articles
+
+I use [Pocket](https://getpocket.com) as my read-it-later app for internet articles and other content. Mydiary connects to the [Pocket API](https://getpocket.com/developer/) to get the articles I saved, read, and/or favorited on a given day.
+
+### Spotify tracks
+
+I mainly use [Spotify]https://www.spotify.com) to listen to music. Mydiary uses the [Spotipy](https://pypi.org/project/spotipy/) Python library to get my listening history and collect all of the songs I listened to in a day.
+
+## Development
+
+### .env file
 
 Set the following environment variables in a `.env` file:
 
@@ -19,13 +53,11 @@ JOPLIN_NOTEBOOK_ID=
 GOOGLECALENDAR_TOKEN_CACHE=
 GOOGLECALENDAR_CREDENTIALS_FILE=
 GOOGLEPHOTOS_TOKEN_CACHE=
-HABITICA_USER_ID=
-HABITICA_API_TOKEN=
 NEXTCLOUD_URL=
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
 ```
-## Alembic
+### Alembic
 
 After making changes or adding or removing any database models (`SQLModel` models with `table=True`), run:
 
@@ -35,10 +67,10 @@ alembic revision --autogenerate -m "REVISION DESCRIPTION"
 alembic upgrade head
 ```
 
-## Code coverage
+### Code coverage
 
 `pytest --cov=mydiary tests/ --cov-report xml:cov.xml`
 
-## API codegen
+### API codegen
 
-If you change anything in the API (`api.py`), you can update the client (`api.ts`) by running `npm run generateClientAPI`.
+Mydiary uses [Orval](https://orval.dev/) to generate client API code from the OpenAPI spec generated by FastAPI. If you change anything in the API (`api.py`), you can update the client (`api.ts`) by running `npm run generateClientAPI`.