xwalton/oyster

Monorepo that houses ColorStack's core product software.

Oyster: The open-source software that powers the ColorStack community experience. ✊🏿✊🏾✊🏽✊🏼

Website | Family Application

Applications

• Member Profile - Serves as the home for a ColorStack member, allowing them to manage their information, find and connect with other members, as well as events and gamification.
• Admin Dashboard - An internal dashboard that the ColorStack team uses to manage important workflows like application review.
• API - Handles all background jobs as well as any webhook integrations that we have with external services.

Understanding the Codebase

Important Tools & Technologies

Here is a list of important tools and technologies that power the ColorStack codebase:

• BullMQ to queue and process jobs asynchronously (in the background).
• Kysely to query our SQL database in a type-safe way.
• Node.js...because yes!
• PostgreSQL to store all of our data.
• Railway to host our applications and databases.
• Redis to store simple key/value based data.
• Remix/React to build fast, accessible and delightful UI experiences.
• Tailwind because scaling CSS is hard.
• Turborepo to manage the build system for our Typescript monorepo.
• Typescript because we like Javascript...and we like type checking.
• Zod to validate all of our data and automatically generate types.

Folder Structure

Here is the structure of our Typescript monorepo:

apps
|--- admin-dashboard
|--- api
|--- member-profile
packages
|--- core
|--- email-templates
|--- types
|--- ui
|--- utils

The apps directory houses all of our applications (see "Applications" section).

The packages directory contains reusable pieces of code that are used across our applications.

• core: Nearly all of our business logic, including our database layer and more. Will eventually colocate feature-based UI next to its related business logic.
• email-templates: React-based email templates built with Resend.
• types: Miscellaneous types shared across applications.
• ui: Reusable UI components built in React.
• utils: Reusable utility functions, such as sleep.

CI Pipeline (GitHub Actions)

To ensure that we don't have any breaking changes, we have a GitHub Actions workflow that runs, which can block a PR from being merged if certain checks don't pass.

For more information on how that CI pipeline works, see this file.

Deployment

We use Railway to host our applications as well as our PostgreSQL and Redis databases. Whenever we make some changes to our main branch, Railway will automatically pick up those changes and deploy a new version of our applications.

Each application has a railway.json file where we can configure certain settings and instructions so Railway knows how and when to build/start our application. See this file as an example. For a full list on what we can configure, see here.

Contributing

Please see our contributing guide! 👋