From 7e631810e9dbff1555b25f73153d669e6b4c8b34 Mon Sep 17 00:00:00 2001
From: Cailyn Sinclair <choover11@gmail.com>
Date: Sat, 17 May 2025 09:55:51 -0700
Subject: [PATCH] docs: add jwt key generation steps

---
 README.md                             | 56 +++++++++++++++++++++++++++
 packages/frontend-common/README.md    | 10 +++--
 packages/frontend-common/package.json |  2 +-
 3 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a763755..17438d7 100644
--- a/README.md
+++ b/README.md
@@ -73,3 +73,59 @@ graph TD
     J --> K[(Their database)]
     end
 ```
+
+## Getting Started
+
+This repository is managed with **Yarn workspaces** and **Lerna**. You will need
+Node.js 16 (see `.nvmrc`) and Yarn 1 installed.
+
+1. Install dependencies and bootstrap all packages:
+   ```bash
+   yarn install
+   ```
+2. Start the databases required by the services:
+   ```bash
+   docker-compose up -d
+   ```
+   This launches `api` on port `5432` and `notifapi` on port `5433`.
+3. Run every package in development mode:
+   ```bash
+   yarn dev
+   ```
+   Individual apps can be started with `yarn dev:webapp`, `yarn dev:www`,
+   `yarn dev:projector` and `yarn dev:admin`.
+4. Copy the sample environment files when present. For example the webapp has
+   `src/.env.development.local.sample` which should be copied to
+   `src/.env.development.local`.
+
+The GraphQL API will be available on port `8080` once the server package starts
+and Vite will launch the frontend apps on their respective ports.
+
+### Generating JWT keys
+
+The API signs tokens using an RSA key pair. You can either expose the keys via
+the `PRIVATE_KEY` and `PUBLIC_KEY` environment variables or place `private.key`
+and `public.key` files in the `packages/server` directory.
+
+```bash
+# create a private key
+openssl genrsa -out packages/server/private.key 2048
+
+# create the matching public key
+openssl rsa -in packages/server/private.key -pubout -out packages/server/public.key
+```
+
+If the environment variables are present they will be used instead of the local
+files when the server starts.
+
+## Contributing
+
+Formatting is handled by **Prettier** and the pre-commit hook runs
+`lerna run lint`. Before opening a pull request run:
+
+```bash
+npx lerna run lint
+```
+
+Feel free to open issues or pull requests against the `main` branch once your
+changes are tested locally.
diff --git a/packages/frontend-common/README.md b/packages/frontend-common/README.md
index b114c5c..4af70bb 100644
--- a/packages/frontend-common/README.md
+++ b/packages/frontend-common/README.md
@@ -1,11 +1,13 @@
 # `@notifycomp/frontend-common`
 
-> TODO: description
+Shared TypeScript utilities for the various frontend applications. Currently this
+package exposes helper functions for date and time formatting that are consumed
+by both the admin and public websites.
 
 ## Usage
 
-```
-const frontendCommon = require('@notifycomp/frontend-common');
+```ts
+import { formatDateRange } from '@notifycomp/frontend-common';
 
-// TODO: DEMONSTRATE API
+console.log(formatDateRange('2023-01-01', '2023-01-05'));
 ```
diff --git a/packages/frontend-common/package.json b/packages/frontend-common/package.json
index 1d00f45..54fb391 100644
--- a/packages/frontend-common/package.json
+++ b/packages/frontend-common/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@notifycomp/frontend-common",
   "version": "0.0.1",
-  "description": "> TODO: description",
+  "description": "Shared utilities for competition schedule frontends",
   "author": "Choover <choover11@gmail.com>",
   "homepage": "https://github.com/coder13/competition-schedule-live#readme",
   "license": "ISC",