docs(contributing): Updated contributing section to include more information around project structure and development

CONTRIBUTING.md

@@ -3,86 +3,70 @@
 Any development help on this project is more than welcome!
 New features should be developed in feature branches, and then will be merged into the `prod` branch to deploy to production.
 
-New features can be gated behind feature flags, until they are fully tested, which I can create from [posthog](posthog.com/). We can work out the details whenever you create a pull request for your work!
+New features can be gated behind feature flags until they are fully tested.
+See the `src/hooks/featureFlags` folder for examples.
+We can work out the details whenever you create a pull request for your work!
 
-### Setup
+## Development Setup
 
-1. Clone this project `git clone https://github.com/scottbenton/Iron-Fellowship.git`
-1. Install dependencies `npm i`
-1. Create an `.env.local` file (see `.env.local` below)
-1. Set up firebase (see Firebase Setup below)
-1. Run `npm run dev` and go to your browser to see the output.
+In order to work on this app, you will need to clone this repository and run it locally.
+See [SETUP.md](./SETUP.md) for instructions on how to get everything running.
 
-### .env.local
+## Picking Up Tickets
 
-Create a new file in the root of this repository, named `.env.local`.
-This file will hold environment variables representing credentials needed to connect your instance with firebase.
+My todo list for this application can be found [here](https://github.com/users/scottbenton/projects/5/views/13).
+If you would like to work on something that is not on that list, please open up an issue or reach out on discord so that we can discuss your proposed changes!
+I don't want you spending time on something that doesn't fit with the application.
+If you are new to the project, I would recommend looking for issues that are tagged with `good first issue`.
+The tickets I've created are not well fleshed out, so feel free to ask any clarifying questions you have before you begin!
 
-Copy the following into your project
+## Swapping between Iron Fellowship and Crew Link in development
 
-```
-VITE_IRON_FELLOWSHIP_FIREBASE_APIKEY=
-VITE_IRON_FELLOWSHIP_FIREBASE_AUTHDOMAIN=
-VITE_IRON_FELLOWSHIP_FIREBASE_PROJECTID=
-VITE_IRON_FELLOWSHIP_FIREBASE_STORAGEBUCKET=
-VITE_IRON_FELLOWSHIP_FIREBASE_MESSAGINGSENDERID=
-VITE_IRON_FELLOWSHIP_FIREBASE_APPID=
+In order to switch between the different systems while running locally, click the settings icon in the bottom left, and then click "Switch System" to swap your local environment to a different game.
 
-VITE_CREW_LINK_FIREBASE_APIKEY=
-VITE_CREW_LINK_FIREBASE_AUTHDOMAIN=
-VITE_CREW_LINK_FIREBASE_PROJECTID=
-VITE_CREW_LINK_FIREBASE_STORAGEBUCKET=
-VITE_CREW_LINK_FIREBASE_MESSAGINGSENDERID=
-VITE_CREW_LINK_FIREBASE_APPID=
+![Settings Icon Menu / Switch System](readme_assets/LocalDevSwitchSystems.png)
 
-# Default values for the environment.
-VITE_TITLE="Starforged Crew Link"
-VITE_FAVICON_PATH=/crew-link-logo.svg
-VITE_OPENGRAPH_PATH=/assets/starforged/opengraph-default.png
-```
+## Important Libraries
 
-As you create firebase projects, you will get values to fill these config values in.
-Copy those values from into your `.env.local` file in the following properties:
+- [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction) - used for storing global state across the application. I use it as an intermediary between the database and individual components
+- [Firebase](https://firebase.google.com/docs) - A backend-as-a-service. Firebase provides authentication, a database, and image storage for the app, as well as a library to interact with those pieces.
+- [Material UI](https://mui.com/material-ui/getting-started/) - The component library that drives the styling in this project.
+- [Datasworn](https://github.com/rsek/datasworn) - rsek's incredible work that has digitized the rules of Ironsworn games and allows for easy interactions between them.
 
-### Firebase Setup
+## File Structure & Organization
 
-Firebase provides authentication, database, and image storage to this application.
+This project has grown a lot further than I originally intended. Because of that, its a lot messier than I intended. However, I try to generally follow this structure in order to keep a little bit of the chaos contained.
 
-The first step is to create firebase projects for Ironsworn and Starforged. You can create a new project by going to the [firebase console](https://console.firebase.google.com/). Once you have created a project, you need to follow the following steps.
+### Data Flow
 
-#### Add an App
+Our data is stored in a Firestore instance. This database is built for real-time sync applications such as ours, and most of the connections in our app need to reflect this. A transaction with the database to fetch data is often not a one-time call, but instead keeps a websocket connection open in order to continually fetch the latest updates from the firebase backend.
 
-1. From the homepage, under the `Get started` section, click `</>`.
-1. Give your app a nickname, and if you plan on hosting your own version (and not just contributing to the existing deployments), click "Also set up Firebase Hosting"
-1. Click next, and copy the apiKey, authDomain, projectId, storageBucket, messagingSenderId, and appId values into your `.env.local` file you created earlier
-1. Complete your setup
+In order to organize the flow of data, we keep all of our interactions with Firestore in the `api-calls` directory. Every function that we write that interacts with the database should go in here.
 
-![Firebase Web App Setup](./readme_assets/FirebaseWeb.png)
+From there, we need to organize the data we receive (and the mutations we can call to update it) in a single spot. In order to do this, we write a zustand state slice `stores/*`. From within this slice, we handle organizing, grouping, and exposing actions to the rest of the UI.
 
-#### Authentication
+Once our data is organized, we can begin to use it on the frontend. We often need to create and call a listener hook (ex: [useListenToNPCs](src/stores/world/currentWorld/npcs/useListenToNPCs.ts)) in order to get the data populated into zustand. From there, we can begin to consume data from the store, and dispatch actions back through the store in order populate our UI and update the database with changes.
 
-1. Under the `Build` tab on the left, select `Authentication`
-1. Click `Get Started`
-1. Select and enable `Google`
-1. Add a new provider, and enable `Email/Password` with `Email link` sign in
+### File Organization
 
-#### Firestore
+Try your best to abide by the following "organization", but don't let it worry you! I certainly haven't perfectly followed it either! If I see anything too far off I'll throw up a comment on a pull request!
 
-1. Under the `Build` tab on the left, select `Firestore Database`
-1. Create a new database, choosing the location of your choice.
-1. Once your database has been provisioned, click the `rules` tab, and copy the contents of the `firestore.rules` file into the tab
+| Folder     | Purpose                                                                                                                                                                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| api-calls  | Handles organizing firestore read & write operations                                                                                                                                                                                              |
+| assets     | Stores static assets (like icons) that are used across the app                                                                                                                                                                                    |
+| components | Stores components & hooks that are not specific to one page - generic components are kept under `components/shared`, while components that relate to a specific feature are under `components/features`                                           |
+| config     | Exports configuration needed for third-party libraries                                                                                                                                                                                            |
+| data       | Organizes and re-exports data from the datasworn library in a way that works well for our applications                                                                                                                                            |
+| functions  | Helper functions that aren't react-specific should go here                                                                                                                                                                                        |
+| hooks      | Custom react hooks should go here. If the hook deals with logic that is specific to a certain component or a certain part of the application, it might be better suited to be stored with that component. Use your best judgement!                |
+| lib        | Similar to config, contains a few functions needed for third-party libraries                                                                                                                                                                      |
+| pages      | Each page in our apps has a component here. If that page contains components that are only needed for that page, those should be contained here as well. If the component is needed across pages, the `components` folder should be used instead. |
+| providers  | A few React context providers. ThemeProvider houses the theme variables for the application                                                                                                                                                       |
+| stores     | Configuration for zustand. Contains the main global data store for this application                                                                                                                                                               |
+| types      | Typescript typings for different features & database objects                                                                                                                                                                                      |
 
-#### Cloud Storage
+## Getting Help
 
-1. Under the `Build` tab on the left, select `Storage`
-1. Set up cloud storage, and wait for it to be created
-1. Once your storage has been created, click the `rules` tab, and copy the contents of the `storage.rules` file into the tab
-
-### Posthog Setup (OPTIONAL)
-
-Posthog gives us some light analytics (page views), and the ability to gate new features behind feature flags. If you need to set up posthog you can create a new project and then add the following to your `.env.local` file
-
-```
-VITE_POSTHOG_KEY=
-VITE_POSTHOG_HOST=
-```
+I am **always** happy to help troubleshoot issues and guide development that you are working on!
+Feel free to reach out to me here, or on Discord (username: scottbenton) for help.

SETUP.md

@@ -0,0 +1,88 @@
+# Setup
+
+## Steps
+
+1. Clone this project `git clone https://github.com/scottbenton/Iron-Fellowship.git`
+1. Install dependencies `npm i`
+1. Create an `.env.local` file (see `.env.local` below)
+1. Set up firebase (see Firebase Setup below, or contact Scott to get credentials to the dev instance)
+1. Run `npm run dev` and go to your browser to see the output.
+
+## .env.local
+
+Create a new file in the root of this repository, named `.env.local`.
+This file will hold environment variables representing credentials needed to connect your instance with firebase.
+
+Copy the following into your project
+
+```
+VITE_IRON_FELLOWSHIP_FIREBASE_APIKEY=
+VITE_IRON_FELLOWSHIP_FIREBASE_AUTHDOMAIN=
+VITE_IRON_FELLOWSHIP_FIREBASE_PROJECTID=
+VITE_IRON_FELLOWSHIP_FIREBASE_STORAGEBUCKET=
+VITE_IRON_FELLOWSHIP_FIREBASE_MESSAGINGSENDERID=
+VITE_IRON_FELLOWSHIP_FIREBASE_APPID=
+
+VITE_CREW_LINK_FIREBASE_APIKEY=
+VITE_CREW_LINK_FIREBASE_AUTHDOMAIN=
+VITE_CREW_LINK_FIREBASE_PROJECTID=
+VITE_CREW_LINK_FIREBASE_STORAGEBUCKET=
+VITE_CREW_LINK_FIREBASE_MESSAGINGSENDERID=
+VITE_CREW_LINK_FIREBASE_APPID=
+
+# Default values for the environment.
+VITE_TITLE="Starforged Crew Link"
+VITE_FAVICON_PATH=/crew-link-logo.svg
+VITE_OPENGRAPH_PATH=/assets/starforged/opengraph-default.png
+```
+
+As you create firebase projects, you will get values to fill these config values in.
+You can also just ask me directly, and I will send you the values I use in development.
+Copy those values from into your `.env.local` file in the following properties:
+
+## Firebase Setup
+
+Firebase provides authentication, database, and image storage to this application.
+
+The first step is to create firebase projects for Ironsworn and Starforged. You can create a new project by going to the [firebase console](https://console.firebase.google.com/). Once you have created a project, you need to follow the following steps.
+
+### Add an App
+
+1. From the homepage, under the `Get started` section, click `</>`.
+1. Give your app a nickname, and if you plan on hosting your own version (and not just contributing to the existing deployments), click "Also set up Firebase Hosting"
+1. Click next, and copy the apiKey, authDomain, projectId, storageBucket, messagingSenderId, and appId values into your `.env.local` file you created earlier
+1. Complete your setup
+
+![Firebase Web App Setup](./readme_assets/FirebaseWeb.png)
+
+### Authentication
+
+1. Under the `Build` tab on the left, select `Authentication`
+1. Click `Get Started`
+1. Select and enable `Google`
+1. Add a new provider, and enable `Email/Password` with `Email link` sign in
+
+### Firestore
+
+1. Under the `Build` tab on the left, select `Firestore Database`
+1. Create a new database, choosing the location of your choice.
+1. Once your database has been provisioned, click the `rules` tab, and copy the contents of the `firestore.rules` file into the tab
+
+### Cloud Storage
+
+1. Under the `Build` tab on the left, select `Storage`
+1. Set up cloud storage, and wait for it to be created
+1. Once your storage has been created, click the `rules` tab, and copy the contents of the `storage.rules` file into the tab
+
+## Posthog Setup (OPTIONAL)
+
+Posthog gives us some light analytics (page views), and the ability to gate new features behind feature flags. If you need to set up posthog you can create a new project and then add the following to your `.env.local` file
+
+```
+VITE_POSTHOG_KEY=
+VITE_POSTHOG_HOST=
+```
+
+---
+
+With that, you should be all set up and ready to develop locally!