# colorstackorg/oyster architecture

> Architecture diagram of the GitHub repository colorstackorg/oyster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/colorstackorg/oyster
- Repository: https://github.com/colorstackorg/oyster

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD

  subgraph "Applications Layer"
    MP["Member Profile (Remix/React)"]:::frontend
    AD["Admin Dashboard (Remix/React)"]:::frontend
    API["API (Node)"]:::backend
  end

  subgraph "Shared Packages"
    CORE["Core (Business Logic)"]:::shared
    UI["UI (Reusable React Components & Tailwind)"]:::shared
    DB["DB (Kysely/PostgreSQL)"]:::shared
    EMAIL["Email Templates (React Emails)"]:::shared
    TYPES["Types and Utils (Shared Types & Utilities)"]:::shared
  end

  subgraph "Infrastructure"
    PG["PostgreSQL Database"]:::database
    REDIS["Redis (BullMQ Backing Store)"]:::database
    OAUTH["OAuth Providers (GitHub/Google/Slack)"]:::external
    SLACK["Slack Service"]:::external
    RESEND["Resend (Email Service)"]:::external
    RAILWAY["Railway (Deployment Platform)"]:::infrastructure
    CICD["GitHub Actions (CI/CD)"]:::infrastructure
  end

  %% Application interactions with Shared Packages
  MP -->|"uses_UI_Core_Types"| CORE
  MP --> UI
  MP --> TYPES

  AD -->|"uses_UI_Core_Types"| CORE
  AD --> UI
  AD --> TYPES

  MP -->|"fetches_data_from"| API
  AD -->|"fetches_data_from"| API

  %% API interactions with Shared Packages and Infrastructure
  API -->|"processes_logic_with"| CORE
  API -->|"executes_DB_operations"| DB
  API -->|"queues_jobs_to"| REDIS
  API -->|"integrates_with"| EMAIL
  API --> TYPES

  CORE -->|"persists_data_via"| DB
  CORE --> TYPES
  DB --> PG

  %% External Services Interactions
  API -->|"triggers_async_jobs"| REDIS
  CORE -->|"handles_auth_via"| OAUTH
  CORE --> SLACK
  EMAIL --> RESEND

  %% CI/CD and Deployment
  CICD -->|"deploys_to"| RAILWAY

  %% Click Events
  click MP "https://github.com/colorstackorg/oyster/tree/main/apps/member-profile/"
  click AD "https://github.com/colorstackorg/oyster/tree/main/apps/admin-dashboard/"
  click API "https://github.com/colorstackorg/oyster/tree/main/apps/api/"
  click CORE "https://github.com/colorstackorg/oyster/tree/main/packages/core/"
  click UI "https://github.com/colorstackorg/oyster/tree/main/packages/ui/"
  click DB "https://github.com/colorstackorg/oyster/tree/main/packages/db/"
  click EMAIL "https://github.com/colorstackorg/oyster/tree/main/packages/email-templates/"
  click TYPES "https://github.com/colorstackorg/oyster/tree/main/packages/types/"
  click TYPES "https://github.com/colorstackorg/oyster/tree/main/packages/utils/"
  click CICD "https://github.com/colorstackorg/oyster/tree/main/.github/workflows/"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
  classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
  classDef shared fill:#fff3cd,stroke:#856404,stroke-width:2px;
  classDef database fill:#f8d7da,stroke:#721c24,stroke-width:2px;
  classDef external fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
  classDef infrastructure fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;

  class MP,AD frontend;
  class API backend;
  class CORE,UI,DB,EMAIL,TYPES shared;
  class PG,REDIS database;
  class OAUTH,SLACK,RESEND external;
  class RAILWAY,CICD infrastructure;
```
