How colorstackorg/oyster works
Main Components
• Applications:
• Member Profile: A Remix/React front-end application that lets ColorStack members manage their profiles, connect with each other, and interact with events and gamification features.
• Admin Dashboard: Another Remix/React powered front-end used internally by the ColorStack team to manage workflows such as application review.
• API: A Node-based application that handles background jobs, webhook integrations, and asynchronous processing.
• Shared Packages:
• Core: Contains nearly all of the core business logic that is reused by the applications.
• UI: Houses reusable React components and styling (using Tailwind) for a consistent look and feel across the apps.
• DB: Manages all database concerns including migrations, seeding, and SQL queries (using Kysely with PostgreSQL), as well as testing utilities.
• Email Templates: React-based email templates which integrate with external emailing services like Resend.
• Types and Utils: Shared TypeScript types and utility functions that help maintain type safety and code reuse across the monorepo.
• Infrastructure & External Services:
• PostgreSQL: The main data persistence store.
• Redis: Used for caching and as a backing store for BullMQ to queue asynchronous jobs.
• BullMQ: Manages background jobs and asynchronous tasks.
• Railway: The deployment platform that automatically deploys changes to the applications and databases.
• GitHub Actions (CI/CD): Defined in the .github folder to run tests, linting, and prevent merging breaking changes.
Mapping Relationships and Interactions
• Each front-end application (Member Profile and Admin Dashboard) consumes shared UI components, business logic (from the core package), and often interacts with the API for data requests.
• The API serves as the central hub for processing tasks—including background jobs—and responds to webhook calls as well as health checks.
• The Core package supports both front-end and API by encapsulating business logic and integration with services like authentication (using OAuth with GitHub, Google, and Slack), gamification management, and more.
• The DB package sits at the bottom of the stack, providing a type-safe interface to PostgreSQL and managing schema changes via migrations.
• External services like BullMQ (backed by Redis) are used for handling asynchronous jobs (e.g., sending notifications, processing one-time codes, etc.).
• Railway acts as the deployment orchestrator, with configuration files (railway.json) in each app indicating build and startup instructions.
Architectural Patterns and Principles
• Modular Monorepo Architecture: Clearly separates applications (front-end and API) from shared packages and infrastructure.
• Separation of Concerns: Frontends focus on UI/UX (using Remix/React and Tailwind) while business logic, database operations, and integrations are encapsulated in the core and db packages.
• Asynchronous Processing: Use of BullMQ for background jobs demonstrates a clear separation between synchronous user interactions and offloaded asynchronous tasks.
• Type Safety and Code Reuse: Extensive use of TypeScript and shared types (via the packages/types module) ensures consistency and reduces bugs across the system.