documentation + generate csv script + allocator use env for base url

Author: Dropheart

.gitignore

@@ -21,7 +21,14 @@ logs
 # Local env files
 .env
 .env.*
+*.env
 !.env.example
 
 # the database, lol
-db/
+db/
+
+# generated family csv
+families.csv
+
+# db certfile, in case you need to make local connections
+certfile.crt

README.md

@@ -6,6 +6,8 @@ Mad3 is a fork of [mad2](https://github.com/icdocsoc/mad2), re-written for the g
 
 This project is open-source and free to look at. If you wish to change something about the website, you can open a PR and we shall review it.
 
+Mad3 is written such that future webmasters (and anyone else) should be able to run it purely with an `.env` file, `docker compose up`, and the allocations script. You should never have to edit the code unless you are bugfixing or modifying features.
+
 ## Project structure
 
 Although using Nuxt 3, we have opted to use Nuxt 4 in our build. [`app/`](/app/) contains the frontend while the [`hono/`](/hono/) contains the server.
@@ -23,31 +25,49 @@ docker compose build
 ```
 
 Now run the postgres image.
+
 ```bash
 # If you want to run it in the background
 docker compose start postgres
-# You will need to then later run 
+# You will need to then later run
 # docker compose stop postgres
 
 # If you want to run it in the foreground to see the logs
 docker compose up postgres
 ```
 
 Finally, run the website.
+
 ```bash
 # The --bun is required as bunfigs are broken, as of writing this.
 bun run --bun dev
 ```
 
+We run the website this way rather than using the Docker image as we want hot-reload and other development features.
+
 ## Production
 
-Docker images are made available for easy running on prod.
+Docker images are made available for easy running on prod. See the local development section for an explanation of how to fill out the environment variables.
+
+To simulate a production run locally, run
+
+```bash
+docker compose build
+
+docker compose up
+```
+
+Note that published Docker builds are generated from the branch `release/latest`.
 
-## Allocations
+## Allocations & more
 
-Run `run.py` in the allocations folder.
+Clone the repo locally and run `run.py` in the allocations folder. You can find your auth cookie from the developer tools (CTRL + SHIFT + I) -> Network -> refresh the page and see the Cookie tab of the request.
 
-You can find your auth cookie from the developer tools (CTRL + SHIFT + I) -> Network -> refresh the page and see the Cookie tab of the request.
+Once the allocations are done, run `generateCsv.ts` to generate a CSV file that you can import into Excel and print out, for on the day organization. There also exists the admin page to facilitate this, but paper never goes wrong.
+
+There also exists an admin page at `/admin` restricted to webmasters as per the env file, where you can search families, see statistics, and change the state of the website.
+
+Should you intend to use this code outside of an Imperial context, you will need to change the sign in code, callback code, and `isFresherOrParent` function. These are found in [`hono/auth/auth.ts`](/hono/auth/auth.ts) and [`hono/auth/jwt.ts`](/hono/auth/jwt.ts).
 
 ## Contributors
 
@@ -56,5 +76,6 @@ You can find your auth cookie from the developer tools (CTRL + SHIFT + I) -> Net
 - [@cybercoder-naj](https://github.com/cybercoder-naj)
 - [@Dropheart](https://github.com/Dropheart)
 
-### mad2 Allocator Author 
+### mad2 Allocator Author
+
 - [@jackpordi](https://github.com/jackpordi)

allocations/allocator/allocate.py

@@ -244,8 +244,8 @@ def allocations_request(families, url=LOCAL_URL):
 
 def allocate(auth, dry=True, url=LOCAL_URL, debug=False, max_children=MAX_CHILDREN):
     cookies = {"Authorization": auth}
-    families = requests.get(url + "api/admin/allocations/all-families", cookies=cookies)
-    freshers = requests.get(url + "api/admin/allocations/all-unallocated-freshers", cookies=cookies)
+    families = requests.get(url + "/api/admin/allocations/all-families", cookies=cookies)
+    freshers = requests.get(url + "/api/admin/allocations/all-unallocated-freshers", cookies=cookies)
 
     if debug:
         print(json.dumps(families.json(), indent=4))
@@ -275,7 +275,7 @@ def allocate(auth, dry=True, url=LOCAL_URL, debug=False, max_children=MAX_CHILDR
     if input("Would you like allocate as per the above? (y/n) ") == 'y':
         # Construct allocations request to backend
         req = allocations_request(families, url=url)
-        response = requests.post(url + "api/admin/allocations", json=req, cookies=cookies)
+        response = requests.post(url + "/api/admin/allocations", json=req, cookies=cookies)
         print(response)
     else:
         print("Allocation cancelled")

allocations/requirements.txt

@@ -5,3 +5,4 @@ rstr
 scikit-learn
 matplotlib
 requests
+python-dotenv

allocations/run.py

@@ -1,4 +1,10 @@
+import os
 from allocator.allocate import allocate
+from dotenv import load_dotenv
+
+load_dotenv('../.env');
+
+BASE_URL = os.getenv('BASE_URL')
 
 authCookie = input("Please insert your auth cookie:\nThis will only be saved in memory to do the allocations.\nSee the README if you're unsure how to get this.\n")
-allocate(authCookie, url="https://family.docsoc.co.uk/")
+allocate(authCookie, url=BASE_URL)

generateCsv.ts

@@ -0,0 +1,28 @@
+import type { Student } from './hono/types';
+
+var csv =
+  'id,parent1,parent1shortcode,parent2,parent2shortcode,child1,child1shortcode,child2,child2shortcode,child3,child3shortcode,child4,child4shortcode\n';
+
+const authCookie = prompt(
+  "Please insert your auth cookie:\nThis will only be saved in memory to create the CSV.\nSee the README if you're unsure how to get this.\n"
+)!;
+
+const req = await fetch(`${process.env.BASE_URL!}/api/admin/all-families`, {
+  headers: {
+    Cookie: `Authorization=${authCookie}`
+  }
+})
+
+const allFamilies = await req.json();
+
+for (const family of allFamilies) {
+  const familyId = family.id;
+
+  const kidsString = family.kids
+    .map((student: Student) => `${student.name},${student.shortcode}`)
+    .join(',');
+
+  csv += `${familyId},${family.parents[0].name},${family.parents[0].shortcode},${family.parents[1].name},${family.parents[1].shortcode},${kidsString}\n`;
+}
+
+await Bun.write('families.csv', csv);

hono/README.md

@@ -3,6 +3,7 @@
 ## API Reference
 
 > Note that where 400 indicates multiple errors, a relevant error message will be returned by the backend.
+> Types can be found in types.ts. This documentation will sometimes use the type definition instead of a type name, for ease of reading.
 
 # **middleware**
 
@@ -145,18 +146,6 @@ type Response = {
 **200** - Returns family.
 
 ```ts
-type Student = {
-  shortcode: string;
-  jmc: boolean;
-  role: "parent" | "fresher";
-  completedSurvey: boolean;
-  name: string | null;
-  gender: "male" | "female" | "other" | "n/a" | null;
-  interests: Interests | null;
-  socials: string[] | null;
-  aboutMe: string | null;
-}
-
 {
   parents: [
     parent1: Student
@@ -170,7 +159,7 @@ type Student = {
 
 ## `GET /state`
 
-**200** - returns JSON with current state.
+**200** - Returns JSON with current state.
 
 ```ts
 {
@@ -189,3 +178,72 @@ type Student = {
 **400** - Invalid body.
 
 **200** - Updated state.
+
+## `GET /allocations/all-families` - admin
+
+**200** - Returns array of all families in the format the allocator wants.
+
+```ts
+{
+  _id: number,
+  parents: {
+    proposerId: AllocatorParent
+    proposeeId: AllocatorParent
+  }
+  kids: AllocatorFresher[]
+  hasFemale: boolean,
+  hasJmc: boolean
+}[]
+```
+
+## `GET /allocations/all-unallocated-freshers` - admin
+
+**200** - Returns array of all freshers who aren't in a family.
+
+```ts
+AllocatorFresher = {
+  _id: string,
+  student: AllocatorStudent
+  interests: Interests
+  family: number | undefined
+}[]
+```
+
+## `POST /allocations` - admin
+
+```ts
+{
+  fresher: string,
+  family: number
+}
+```
+
+**200** - Successfully allocated students to families.
+
+**400** - Invalid body.
+
+## `GET /stats` - admin
+
+**200** - Returns various stats about the families and freshers.
+
+```ts
+{
+  families: number, // num of marriages
+  all_parents: number, // non-freshers who signed in at least once
+  registered_parents: number, // non-freshers who completed the survey
+  all_freshers: number, // all freshers, due to the seed file
+  registered_freshers: number // freshers who completed the survey
+}
+```
+
+## `GET /all-families` - admin
+
+**200** Returns all families. This differs from the allocation routes, as it uses our sensible types.
+
+```ts
+{
+  id: number,
+  parents: Student[],
+  kids: Student[]
+}[]
+```