Add some docs about architecture (#459)

#128

Reviewed-on: #459
Reviewed-by: Shahan Neda <snedadah@csclub.uwaterloo.ca>

README.md

@@ -1,6 +1,13 @@
-# Development
+# README
 
-## Dependencies
+## Documentation
+
+- [Architecture and Folder Structure](docs/architecture.md)
+- [Everything about pages](docs/pages.md)
+
+## Development
+
+### Dependencies
 
 Make sure that you have `node` >= 14 and `npm` >= 7. Node 14 ships with npm v6,
 so if you're using node 14, you would need to upgrade npm. Alternatively you
@@ -8,19 +15,20 @@ could also upgrade to node 16, which ships with npm 7.
 
 How to upgrade npm: `npm i -g npm`
 
-## Local
+### Local
 
 - `npm install` to install project dependencies
+- `npm run build:images` to optimize images for the first time after cloning
 - `npm run dev` to run the dev server (http://localhost:3000)
 
-## Production
+### Production
 
 - `npm install` to install project dependencies
 - `npm run build` to generate html/css/js
 - `npm run export` to move the built files (along with assets in the public directory) to the `/out` directory
 - Use your favourite web server to host the files in the `/out` directory. (A very simple one would be `python -m http.server` - not sure if it should actually be used for production :P)
 
-# Deploy
+## Deploy
 
 - `groups` (make sure you're in the `www` group)
 - `curl -o- https://git.csclub.uwaterloo.ca/www/www-new/raw/branch/main/deploy.sh | bash` (run on `caffeine`)

docs/architecture.md

@@ -0,0 +1,62 @@
+# Architecture and Folder Structure
+
+The diagram below shows a general overview of how the website is architected. A thin black arrow on the graph depicts a dependency.
+
+Legend:
+
+- <span style="background: #dae8fc;">Blue</span>: React components
+- <span style="background: #f8cecc;">Red</span>: Code or assets that only exist during build time
+- <span style="background: #d5e8d4;">Green</span>: Static assets that exist during runtime on the server
+
+![diagram](static/architecture.svg)
+
+## <code style="background: #dae8fc;">/pages</code>
+
+This folder acts as the entry point for the our website. Pages are not built as reusable components, but rather as an outline of our website. All dynamically generated pages use the functionality exposed by the `/lib` folder. There are some folders that directly use the items in the `/content` folder directly.
+
+Look at the [docs about pages](pages.md) to learn more about them.
+
+## <code style="background: #dae8fc;">/components</code>
+
+Components are the building blocks of our website. Most of our components are simple functional components that do not do much except making the UI look nice. Almost all of our components have no dependencies except `react`, `date-fns`, and other components from the `/components` folder. This structure allows us keep components and design separate from the business logic of the website making it easier to split them off into their own mini design framework if necessary.
+
+## <code style="background: #f8cecc;">/scripts</code>
+
+These contain scripts that run during the CI/CD phase to insert dynamically generated assets into the public folder - this is what the thick red arrow is referring to.
+
+The two main scripts that we have today are:
+
+- `generate-calendar` (`npm run build:calendar`): to generate an ical file that consumes events using the `/lib` folder - writing the resulting file to `public/events.ics`
+- `optimize-images` (`npm run build:images`): to optimize images present in the `images` folder and write the optimized images in the `public/images` folder for the website to consume. You **must run it at least once after cloning** the repository so that you can see all the images during development.
+
+## <code style="background: #f8cecc;">/lib</code>
+
+This folder acts as an API layer for the website. It mainly adds helper functions to access the data in the `/content` folder easily, with the exception of `/lib/members.ts` - which uses LDAP to query CSC members.
+
+## <code style="background: #f8cecc;">/content</code>
+
+All the `.md` files in this folder are used by the `/lib` folder to provide an API over them. These markdown files may or may not have some metadata at the top written in yaml, which we parse using the `gray-matter` library.
+
+Example of the metadata:
+
+```
+---
+foo: i am some metadata
+bar: some more
+baz: ok last one
+---
+
+# This is not metadata
+```
+
+**Note**: The `.mdx` files under this folder are directly used in `/pages`. They are automatically converted to react components on the fly.
+
+## <code style="background: #f8cecc;">/images</code>
+
+These are the unoptimized images that you see on the website. They are consumed by the `optimize-images` script to ... optimize them ... before putting them in the `/public/images` folder. We need to optimize images in order to decrease the latency of the website.
+
+## <span style="background: #d5e8d4;">`/public`</span>
+
+This is the folder that contains all the static assets of the website. Everything in here is accessible at `https://csclub.uwaterloo.ca/[asset file name]`
+
+For example `/public/fonts/future-bold.woff` is available at `https://csclub.uwaterloo.ca/fonts/future-bold.woff`.

docs/static/architecture.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-06-06T07:02:10.844Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" etag="Yv6lipB2xa6Es_IGroX6" version="19.0.0" type="device"><diagram id="to5jL6O8asY2GUfFvI2Z" name="Page-1">7Vpbb5swFP41PLYCcwl5bNN21bRJkzpp66MD5rIZzIxpyH79DNgBU9IlKQ2oqlSp+Fx8Od/n42OIZq6S8hOFWfSV+AhrQPdLzbzRADAsALTqT/e3jWQBnEYQ0tgXRq3gIf6LhFAX0iL2Ua4YMkIwizNV6JE0RR5TZJBSslHNAoLVUTMYomeCBw/i59Ifsc+iRuraeiu/R3EYyZENXWgSKI2FII+gTzYdkXmrmStKCGueknKFcBU8GZfG726PdjcxilJ2iENmFJ/L5DE0svjeXIKoKL+zC9HLE8SFWLAGHMz7uw4I75bPmm1FKJw/BZGKi7wG6oobGFbGwb5u9VWUoaf6rEiaEwzzrpUTNv/vqhjmcljebkaWaqBMAlBSpD6qlmRw9SaKGXrImuE2nIFcFrEEC3UQY7wimNDa1/QhcgOPy3NGyW/U0Tiei9bBbrwnRBkq98bZ2KHHaY9IghjdchPpYNuNy1YyWRBg0/LHkKSIOtxxhAwKyoa7rltU+YMA9hiQrQGUe3FFPqe9aBLKIhKSFOLbVnrdRl7nrdbmCyGZiPcvxNhW7GFYMNJDg+MqlHxGMtbVwC9Hms+TFFQwaniFYj0M0hCxF+zMYeQowpDFT+o8RocBzGCv4Xh9jp0WuB7yBnfa2rUtWx9np4GFutOANfVOM2cAMT8JGapxrQde01b3XoE33amBH8qw5wc+yUjKQ5hPg/15jldTn9metw84XFP/qqpFecvj6OWxpwZSPVr75yQqY/az0l3aovUo/Krnm1K41Y2tbKR8aY3Twpbtx66y9atb0nHEQ1mW6/87lK1hvDuA2gN4StnBZ7cY4RuJ6w0p6WSpqWSx7PGkWabw6pbX/Y6WvY6sXkdNHJ51VHNut+zTaejOIANlxRpzbk+TfWzk+tZQ9nHB2nSccbKP00s/0xf3yxngnns0zqY6ds5TcpjLuQEv35BMinycdC/v7xF425hbwWEMXSTHrTja6gEcVT2cUqpMUHGAKSsOo5dJdq86j604dkyUKanPuDeuOIyh2+5b8fC4KnZiHi4/eHhOHi4+8uHreGjo2oREtHSVPxY4kYiWrXZkLs5MxKE7WI+IeQSz6jHAqBSMvB6LnAozL+0DuWl0mNnydJibh1VgPgpggdk0XHY/qDwGlYeulaPm1H2U6VKslb6W5DMvSPd8lzoPaUH/hnNqIdAnLTjwFRhnEdx2zLLKIH9pwuqrNstQvnzzh6bHA3cEb7Zf4Rvz9rcM5u0/</diagram></mxfile>