Include documentation for API and subcrates

README.md

@@ -3,8 +3,6 @@
 Align your schedules to find the perfect time that works for everyone.
 Licensed under the GNU GPLv3.
 
-<a href="https://www.producthunt.com/posts/crab-fit?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-crab-fit" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=291656&theme=light" alt="Crab Fit - Use your availability to find a time that works for everyone | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
-
 ## Contributing
 
 ### ⭐️ Bugs or feature requests
@@ -17,14 +15,13 @@ If you speak a language other than English and you want to help translate Crab F
 
 ## Setup
 
-1. Clone the repo.
+1. Clone the repo and ensure you have `node`, `yarn` and `rust` installed on your machine.
-2. Run `yarn` in both backend and frontend folders.
+2. Run `yarn` in `frontend` folder to install dependencies, then `yarn dev` to start the dev server.
-3. Run `yarn dev` in the backend folder to start the API. **Note:** you will need a google cloud app set up with datastore enabled and set your `GOOGLE_APPLICATION_CREDENTIALS` environment variable to your service key path.
+3. Run `cargo run` in the `api` folder to start the API.
-4. Run `yarn dev` in the frontend folder to start the frontend.
 
 ### 🔌 Browser extension
 
-The browser extension in `crabfit-browser-extension` can be tested by first running the frontend, and changing the iframe url in the extension's `popup.html` to match the local Crab Fit. Then it can be loaded as an unpacked extension in Chrome to test.
+The browser extension in `browser-extension` can be tested by first running the frontend, and changing the iframe url in the extension's `popup.html` to match the local Crab Fit. Then it can be loaded as an unpacked extension in Chrome to test.
 
 ## Deploy
 
@@ -34,4 +31,4 @@ To deploy cron jobs (i.e. monthly cleanup of old events), run `gcloud app deploy
 
 ### 🔌 Browser extension
 
-Compress everything inside the `crabfit-browser-extension` folder and use that zip to deploy using Chrome web store and Mozilla Add-on store.
+Compress everything inside the `browser-extension` folder and use that zip to deploy using Chrome web store and Mozilla Add-on store.

api/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "crabfit_backend"
+name = "crabfit-api"
 description = "API for Crab Fit"
 license = "GPL-3.0-only"
 version = "2.0.0"

api/README.md

@@ -0,0 +1,26 @@
+# Crab Fit API
+
+This is the API for Crab Fit, written in Rust. It uses the [axum](https://crates.io/crates/axum) framework to run a HTTP server, and supports multiple storage adaptors.
+
+## API docs
+
+OpenAPI compatible API docs are generated using [utoipa](https://crates.io/crates/utoipa). You can visit them at [https://api.crab.fit/docs](https://api.crab.fit/docs).
+
+## Storage adaptors
+
+| Adaptor | Works with |
+| ------- | ---------- |
+| `memory-adaptor` | Stores data in memory |
+| `sql-adaptor` | Postgres, MySQL, SQLite |
+| `datastore-adaptor` | Google Datastore |
+
+To choose an adaptor, specify it in the `features` when compiling, e.g. `cargo run --features sql-adaptor`.
+
+Some adaptors require environment variables to be set. You can specify them in a `.env` file and they'll be loaded in using [dotenvy](https://crates.io/crates/dotenvy). See a specific adaptor's readme for more information.
+
+> **Note**
+> `memory-adaptor` is the default if no features are specified. Ensure you specify a different adaptor when deploying.
+
+### Adding an adaptor
+
+See [adding an adaptor](adaptors/README.md#adding-an-adaptor) in the adaptors readme.

api/adaptors/README.md

@@ -0,0 +1,21 @@
+# Crab Fit Storage Adaptors
+
+This directory contains sub-crates that connect Crab Fit to a database of some sort. For a list of available adaptors, see the [api readme](../README.md).
+
+## Adding an adaptor
+
+The suggested flow is copying an existing adaptor, such as `memory`, and altering the code to work with your chosen database.
+
+Note, you will need to have the following crates as dependencies in your adaptor:
+
+- `common`<br>Includes a trait for implementing your adaptor, as well as structs your adaptor needs to return.
+- `async-trait`<br>Required because the trait from `common` uses async functions, make sure you include `#[async_trait]` above your trait implementation.
+
+Once you've created the adaptor, you'll need to make sure it's included as a dependency in the root [`Cargo.toml`](../Cargo.toml), and add a feature flag with the same name. Make sure you also document the new adaptor in the [api readme](../README.md).
+
+Finally, add a new version of the `create_adaptor` function in the [`adaptors.rs`](../src/adaptors.rs) file that will only compile if the specific feature flag you added is set. Don't forget to add a `not` version of the feature to the default memory adaptor function at the bottom of the file.
+
+## FAQ
+
+Why is it spelt "adaptor" and not "adapter"?
+> The maintainer lives in Australia, where it's usually spelt "adaptor" 😎

api/adaptors/datastore/Cargo.toml

@@ -7,6 +7,7 @@ edition = "2021"
 async-trait = "0.1.68"
 chrono = "0.4.24"
 common = { path = "../../common" }
+# Uses custom version of google-cloud that has support for NULL values
 google-cloud = { git = "https://github.com/GRA0007/google-cloud-rs.git", features = ["datastore", "derive"] }
 serde = "1.0.163"
 serde_json = "1.0.96"

api/adaptors/datastore/README.md

@@ -0,0 +1,13 @@
+# Google Datastore Adaptor
+
+This adaptor works with [Google Cloud Datastore](https://cloud.google.com/datastore). Please note that it's compatible with Firestore in Datastore mode, but not with Firestore.
+
+## Environment
+
+To use this adaptor, make sure you have the `GCP_CREDENTIALS` environment variable set to your service account credentials in JSON format. See [this page](https://developers.google.com/workspace/guides/create-credentials#service-account) for info on setting up a service account and generating credentials.
+
+Example:
+
+```env
+GCP_CREDENTIALS='{"type":"service_account","project_id":"my-project"}'
+```

api/adaptors/memory/README.md

@@ -0,0 +1,6 @@
+# Memory Adaptor
+
+This adaptor stores everything in memory, and all data is lost when the API is stopped. Useful for testing.
+
+> **Warning**
+> Do not use this adaptor in production!

api/adaptors/sql/README.md

@@ -0,0 +1,13 @@
+# SQL Adaptor
+
+This adaptor works with [Postgres](https://www.postgresql.org/), [MySQL](https://www.mysql.com/) or [SQLite](https://sqlite.org/index.html) databases.
+
+## Environment
+
+To use this adaptor, make sure you have the `DATABASE_URL` environment variable set to the database url for your chosen database.
+
+Example:
+
+```env
+DATABASE_URL="postgresql://username:password@localhost:5432/crabfit"
+```

api/common/README.md

@@ -0,0 +1,3 @@
+# Common
+
+This crate contains the [adaptor trait](./src/adaptor.rs), and structs that are used by it. These are separated into their own crate so that the root crate and the adaptors can import from it without causing a circular dependency.