📝 Zotmeal Docs v1.0

content/docs/contributor/zotmeal/api/index.mdx

@@ -0,0 +1,26 @@
+---
+title: API
+---
+
+import { ServerOff, Database } from "lucide-react";
+
+ZotMeal implements its very own API for use with the project. Information on
+how to extend the API and use it for ZotMeal can be found below.
+
+<Cards>
+  <Card
+    icon={<ServerOff/>}
+    href="/docs/contributor/zotmeal/api/serverless"
+    title="Serverless"
+  > 
+    Cron jobs
+  </Card>
+  <Card
+    icon={<Database/>}
+    href="/docs/contributor/zotmeal/api/trpc"
+    title="tRPC"
+  >
+    Database tasks
+  </Card>
+
+</Cards>

content/docs/contributor/zotmeal/api/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "API",
+  "icon": "Server",
+  "pages": ["serverless", "trpc"]
+}

content/docs/contributor/zotmeal/api/serverless.mdx

@@ -0,0 +1,88 @@
+---
+title: Serverless Functions
+---
+
+import { File, Folder, Files } from "fumadocs-ui/components/files";
+
+As opposed to managing a server backend, ZotMeal uses serverless functions that are ran on-demand in the cloud, with AWS Lambda as our cloud service.
+
+## Cron Jobs
+
+Inside the `./apps/server` folder you will see something like this:
+
+<Files>
+<Folder name="apps/server" defaultOpen>
+ <Folder name="node_modules" defaultOpen/>
+ <Folder name="src" defaultOpen>
+  <Folder name="functions" defaultOpen>
+    <Folder name="cron"/>
+    <Folder name="trpc"/>   
+  </Folder>
+</Folder>
+</Folder>
+</Files>
+
+The `src/functions/trpc` directory is used for creating API endpoints for our tRPC functions (for future work). tRPC helps us write APIs with autocomplete and type checking.
+
+Inside the `src/functions/cron` folder we can find:
+
+<Files>
+<Folder name="cron" defaultOpen>
+ <File name="daily.ts"/>
+ <File name="weekly.ts"/>
+</Folder>
+</Files>
+
+Each of these `.ts` functions corresponds to a specific **cron** job that 
+our app performs.
+
+- **Daily**: Fetches the menu from CampusDishAPI for the current day and inserts
+it into the database. Runs every day at midnight to ensure the most up to date 
+menu information.
+
+- **Weekly**: Fetches all menus from CampusDishAPI for all days at most 2 week 
+away from today. Allows users to see future menus for up to 2 week away.
+
+## Server Functions
+
+The main functionality of these jobs can be found in the `./packages/api/src/server` subdirectory.
+
+#### server/daily
+
+Functions in `parse.ts`:
+
+`getCampusDishMenu`
+	Fetches and parses the CampusDish menu for a given date.
+- Input: `Date`, `RestaurantName`, `string` (periodId)
+- Returns: `CampusDishMenu`
+
+`upsertMenusForDate`
+	Fetches and upserts the CampusDish menu for all periods of a given date.
+- Input: `Date`, `RestaurantName`
+- Returns: None
+
+Functions in `index.ts`
+
+`daily`
+	Performs the daily cron job action: Fetches the menu for the current date and upserts it into the database.
+- Input: `Date`, `RestaurantName`
+- Returns: None
+
+#### server/weekly
+
+`weekly`
+	Performs the weekly cron job action: Fetches the menu for all 14 days after the current date and upserts them into the database.
+- Input: `Date`, `RestaurantName`
+- Returns: None
+
+#### Server/scrapeEvents
+
+`getHTML`
+	Fetches the raw HTML of the page from the URL provided
+- Input: `string` (URL)
+- Returns: `string` (HTML)
+
+`scrapeEvents`
+	Scrapes the events from the events page URL provided to create a list of all upcoming events.
+- Input: `string` (HTML)
+- Returns: `Event[]`

content/docs/contributor/zotmeal/api/trpc.mdx

@@ -0,0 +1,138 @@
+---
+title: tRPC
+---
+
+import { File, Folder, Files } from "fumadocs-ui/components/files";
+
+Taking a look inside the `./packages/api/src` folder we find something like this:
+
+<Files>
+<Folder name="packages/src" defaultOpen>
+	<Folder name="dishes"/>
+	<Folder name="events"/>
+	<Folder name="menus"/>
+	<Folder name="periods"/>
+	<Folder name="ratings"/>
+	<Folder name="restaurants"/>
+	<Folder name="stations"/>
+	<Folder name="users"/>
+</Folder>
+</Files>
+
+Each folder corresponds to a set of tRPC procedures that handles one major feature.
+
+Within each subfolder, we find 2-4 `.ts` files that looks something like this:
+
+<Files>
+<Folder name="dishes" defaultOpen>
+ <File name="router.test.ts"/>
+ <File name="router.ts"/>
+ <File name="services.test.ts"/>
+ <File name="services.ts"/>
+</Folder>
+</Files>
+
+- The `router.ts` file contains tRPC procedures that exported via the tRPC router.
+- The `services.ts` file contains helper functions that are used in the tRPC procedures mentioned above
+- The files with extension `.test.ts` contain tests that run when running `turbo test`. See ***creating tests*** for more information.
+- For our tRPC functions, we use Zod to define and validate schemas for input variables at runtime.
+
+We will now go into detail about each individual tRPC procedure.
+
+## Dishes
+
+#### Procedures
+
+`dish/get` (`getDishProcedure`)
+	Queries the `dishes` table for a dish
+- Input: `string` (dishId)
+
+`dish/rate` (`RateDishProcedure`)
+	Updates the rating of a given dish when users submit a rating
+- Input: `RatingSchema`
+
+#### Services
+
+`upsertDish`
+	Attempts to insert one dish entry into the `dishes` table, along with its `NutritionInfo` and `DietRestrictions`. Upon conflict with `dishes.id`, the old entry is updated with new info.
+- Input: `DishWithRelations`
+- Returns upserted dish on success
+
+`upsertDishToMenu`
+	Attempts to insert a relation in the `dishesToMenu` table. Upon conflict with (`dishesId`, `menusId`) the old relation is updated.
+- Input: `DishToMenu`
+## Events
+
+#### Procedures
+
+`event/upcoming`
+	Queries the `events` table for all events that are happening today or later.
+- Input: None
+#### Services
+
+`upsertEvent`
+	Attempts to insert one event entry into the `events` table. Upon conflict with (`events.title`, `events.start`, `events.restaurantId`), the old entry is updated with new info.
+- Input: `Event`
+
+`upsertEvents`
+	Attempts to insert multiple events into the `events` table. Upon conflict old entries are updated.
+- Input: `DishToMenu`
+- Returns list of successfully upserted events
+## Menus
+
+#### Services
+
+`upsertMenu`
+	Attempts to insert one menu entry into the `menus` table. Upon conflict with `menus.id`, the old entry is updated with new info.
+- Input: `Menu`
+
+## Periods
+
+#### Services
+
+`upsertPeriod`
+	Attempts to insert one period entry into the `periods` table. Upon conflict with `periods.id`, the old entry is updated with new info.
+- Input: `Period`
+
+## Ratings
+
+#### Services
+
+`upsertRatings`
+	Attempts to insert one rating entry into the `ratings` table. Upon conflict with (`ratings.userId`, `ratings.dishId`), the old entry is updated with new info.
+- Input: `Rating`
+
+## Restaurants
+
+#### Services
+
+`upsertRestaurant`
+	Attempts to insert one restaurant entry into the `restaurants` table. Upon conflict with `restaurants.id`, the old entry is updated with new info.
+- Input: `Restaurant`
+
+`getRestaurantsByDate`
+	Queries the database for information on both restaurants corresponding to a given date.
+- Input: `Date`
+- Returns: `ZotmealData`
+## Stations
+
+#### Services
+
+`upsertStation`
+	Attempts to insert one station entry into the `stations` table. Upon conflict with `stations.id`, the old entry is updated with new info.
+- Input: `Station`
+
+## Users
+
+#### Services
+
+`getUser`
+	Queries the `users` table for a user along with their ratings and pins
+- Input: `string` (userId)
+- Returns: \{`User`, `Pin[]`, `Rating[]`\}
+
+`upsertUser`
+	Attempts to insert one user entry into the `users` table. Upon conflict with `users.id`, the old entry is updated with new info.
+- Input: `User`
+
+You may also notice there is `api/src/server` subfolder in this directory. This subfolder contains components relating the the Lambda serverless functions this app performs (see Serverless Functions)