Skip to content

Commit 5eafde5

Browse files
EightBitByteLexTruong
EightBitByte
and
LexTruong
authored
📝 Zotmeal Docs v1.0 (#40)
* docs: 📚️Zotmeal contributor docs in progress * docs: 📚️ 📝 Add frontend, backend, update getting-started * docs: 📚️ add Files components to replace old file sections * docs: 📚️ remove expo troubleshooting * docs: 📚️ replace file code blocks with fumadocs Files * docs: 📚️ replace file code blocks in serverless with fumadocs Files * docs: 📚️ remove table of contents * docs: 📚️ reorg pages into ui/api, reorg components into own page * removed docs for ui components * trpc and lambda description * updated getting started --------- Co-authored-by: Lex Truong <[email protected]>
1 parent 974ce61 commit 5eafde5

File tree

10 files changed

+591
-4
lines changed

10 files changed

+591
-4
lines changed

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: API
3+
---
4+
5+
import { ServerOff, Database } from "lucide-react";
6+
7+
ZotMeal implements its very own API for use with the project. Information on
8+
how to extend the API and use it for ZotMeal can be found below.
9+
10+
<Cards>
11+
<Card
12+
icon={<ServerOff/>}
13+
href="/docs/contributor/zotmeal/api/serverless"
14+
title="Serverless"
15+
>
16+
Cron jobs
17+
</Card>
18+
<Card
19+
icon={<Database/>}
20+
href="/docs/contributor/zotmeal/api/trpc"
21+
title="tRPC"
22+
>
23+
Database tasks
24+
</Card>
25+
26+
</Cards>

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"title": "API",
3+
"icon": "Server",
4+
"pages": ["serverless", "trpc"]
5+
}

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Serverless Functions
3+
---
4+
5+
import { File, Folder, Files } from "fumadocs-ui/components/files";
6+
7+
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.
8+
9+
## Cron Jobs
10+
11+
Inside the `./apps/server` folder you will see something like this:
12+
13+
<Files>
14+
<Folder name="apps/server" defaultOpen>
15+
<Folder name="node_modules" defaultOpen/>
16+
<Folder name="src" defaultOpen>
17+
<Folder name="functions" defaultOpen>
18+
<Folder name="cron"/>
19+
<Folder name="trpc"/>
20+
</Folder>
21+
</Folder>
22+
</Folder>
23+
</Files>
24+
25+
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.
26+
27+
Inside the `src/functions/cron` folder we can find:
28+
29+
<Files>
30+
<Folder name="cron" defaultOpen>
31+
<File name="daily.ts"/>
32+
<File name="weekly.ts"/>
33+
</Folder>
34+
</Files>
35+
36+
Each of these `.ts` functions corresponds to a specific **cron** job that
37+
our app performs.
38+
39+
- **Daily**: Fetches the menu from CampusDishAPI for the current day and inserts
40+
it into the database. Runs every day at midnight to ensure the most up to date
41+
menu information.
42+
43+
- **Weekly**: Fetches all menus from CampusDishAPI for all days at most 2 week
44+
away from today. Allows users to see future menus for up to 2 week away.
45+
46+
## Server Functions
47+
48+
The main functionality of these jobs can be found in the `./packages/api/src/server` subdirectory.
49+
50+
#### server/daily
51+
52+
Functions in `parse.ts`:
53+
54+
`getCampusDishMenu`
55+
Fetches and parses the CampusDish menu for a given date.
56+
- Input: `Date`, `RestaurantName`, `string` (periodId)
57+
- Returns: `CampusDishMenu`
58+
59+
`upsertMenusForDate`
60+
Fetches and upserts the CampusDish menu for all periods of a given date.
61+
- Input: `Date`, `RestaurantName`
62+
- Returns: None
63+
64+
Functions in `index.ts`
65+
66+
`daily`
67+
Performs the daily cron job action: Fetches the menu for the current date and upserts it into the database.
68+
- Input: `Date`, `RestaurantName`
69+
- Returns: None
70+
71+
#### server/weekly
72+
73+
`weekly`
74+
Performs the weekly cron job action: Fetches the menu for all 14 days after the current date and upserts them into the database.
75+
- Input: `Date`, `RestaurantName`
76+
- Returns: None
77+
78+
#### Server/scrapeEvents
79+
80+
`getHTML`
81+
Fetches the raw HTML of the page from the URL provided
82+
- Input: `string` (URL)
83+
- Returns: `string` (HTML)
84+
85+
`scrapeEvents`
86+
Scrapes the events from the events page URL provided to create a list of all upcoming events.
87+
- Input: `string` (HTML)
88+
- Returns: `Event[]`

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

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: tRPC
3+
---
4+
5+
import { File, Folder, Files } from "fumadocs-ui/components/files";
6+
7+
Taking a look inside the `./packages/api/src` folder we find something like this:
8+
9+
<Files>
10+
<Folder name="packages/src" defaultOpen>
11+
<Folder name="dishes"/>
12+
<Folder name="events"/>
13+
<Folder name="menus"/>
14+
<Folder name="periods"/>
15+
<Folder name="ratings"/>
16+
<Folder name="restaurants"/>
17+
<Folder name="stations"/>
18+
<Folder name="users"/>
19+
</Folder>
20+
</Files>
21+
22+
Each folder corresponds to a set of tRPC procedures that handles one major feature.
23+
24+
Within each subfolder, we find 2-4 `.ts` files that looks something like this:
25+
26+
<Files>
27+
<Folder name="dishes" defaultOpen>
28+
<File name="router.test.ts"/>
29+
<File name="router.ts"/>
30+
<File name="services.test.ts"/>
31+
<File name="services.ts"/>
32+
</Folder>
33+
</Files>
34+
35+
- The `router.ts` file contains tRPC procedures that exported via the tRPC router.
36+
- The `services.ts` file contains helper functions that are used in the tRPC procedures mentioned above
37+
- The files with extension `.test.ts` contain tests that run when running `turbo test`. See ***creating tests*** for more information.
38+
- For our tRPC functions, we use Zod to define and validate schemas for input variables at runtime.
39+
40+
We will now go into detail about each individual tRPC procedure.
41+
42+
## Dishes
43+
44+
#### Procedures
45+
46+
`dish/get` (`getDishProcedure`)
47+
Queries the `dishes` table for a dish
48+
- Input: `string` (dishId)
49+
50+
`dish/rate` (`RateDishProcedure`)
51+
Updates the rating of a given dish when users submit a rating
52+
- Input: `RatingSchema`
53+
54+
#### Services
55+
56+
`upsertDish`
57+
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.
58+
- Input: `DishWithRelations`
59+
- Returns upserted dish on success
60+
61+
`upsertDishToMenu`
62+
Attempts to insert a relation in the `dishesToMenu` table. Upon conflict with (`dishesId`, `menusId`) the old relation is updated.
63+
- Input: `DishToMenu`
64+
## Events
65+
66+
#### Procedures
67+
68+
`event/upcoming`
69+
Queries the `events` table for all events that are happening today or later.
70+
- Input: None
71+
#### Services
72+
73+
`upsertEvent`
74+
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.
75+
- Input: `Event`
76+
77+
`upsertEvents`
78+
Attempts to insert multiple events into the `events` table. Upon conflict old entries are updated.
79+
- Input: `DishToMenu`
80+
- Returns list of successfully upserted events
81+
## Menus
82+
83+
#### Services
84+
85+
`upsertMenu`
86+
Attempts to insert one menu entry into the `menus` table. Upon conflict with `menus.id`, the old entry is updated with new info.
87+
- Input: `Menu`
88+
89+
## Periods
90+
91+
#### Services
92+
93+
`upsertPeriod`
94+
Attempts to insert one period entry into the `periods` table. Upon conflict with `periods.id`, the old entry is updated with new info.
95+
- Input: `Period`
96+
97+
## Ratings
98+
99+
#### Services
100+
101+
`upsertRatings`
102+
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.
103+
- Input: `Rating`
104+
105+
## Restaurants
106+
107+
#### Services
108+
109+
`upsertRestaurant`
110+
Attempts to insert one restaurant entry into the `restaurants` table. Upon conflict with `restaurants.id`, the old entry is updated with new info.
111+
- Input: `Restaurant`
112+
113+
`getRestaurantsByDate`
114+
Queries the database for information on both restaurants corresponding to a given date.
115+
- Input: `Date`
116+
- Returns: `ZotmealData`
117+
## Stations
118+
119+
#### Services
120+
121+
`upsertStation`
122+
Attempts to insert one station entry into the `stations` table. Upon conflict with `stations.id`, the old entry is updated with new info.
123+
- Input: `Station`
124+
125+
## Users
126+
127+
#### Services
128+
129+
`getUser`
130+
Queries the `users` table for a user along with their ratings and pins
131+
- Input: `string` (userId)
132+
- Returns: \{`User`, `Pin[]`, `Rating[]`\}
133+
134+
`upsertUser`
135+
Attempts to insert one user entry into the `users` table. Upon conflict with `users.id`, the old entry is updated with new info.
136+
- Input: `User`
137+
138+
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)

‎content/docs/contributor/zotmeal/getting-started.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

0 commit comments

Comments
 (0)