# bluedotimpact/bluedot architecture

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

- Interactive diagram: https://gitdiagram.com/bluedotimpact/bluedot
- Repository: https://github.com/bluedotimpact/bluedot

## Overview

##### Project type and purpose
- This is a monorepo hosting a suite of full‐stack microservices and shared libraries for BlueDot Impact’s custom software. Each “app” under `apps/` (e.g. `website`, `availability`, `meet`, `course-demos`, proxies, Keycloak login, a standalone Node backend) is its own Dockerized service built primarily with Next.js (React + serverless API routes) or Node.js.
- The `libraries/` folder holds shared TypeScript packages (UI components, configs, tooling scripts).
- The `apps/infra/` folder uses Pulumi to declare and deploy a Kubernetes cluster (ingress, cert‐manager, services, persistent volumes, secrets) on Vultr.

##### High-level file structure analysis
- Top‐level folders:
- apps/ – twelve+ front-end/API apps plus a Node backend and Pulumi infra.
- libraries/ – shared UI, lint and TS configurations, docker‐scripts, backend contracts, etc.
- .github/, .devcontainer/, CI/CD workflows, root package.json configure the monorepo, Turbo, GitHub Actions.
- Each app follows the same pattern:
- Dockerfile – multi-stage build.
- src/pages – Next.js pages and API routes.
- src/lib/api/db & migrations – database clients (Postgres via Kysely/Kanel) or Airtable.
- src/lib/api/makeApiRoute + zod validation.
- src/components – React UI (with shared `libraries/ui`).
- .env.* – environment configuration.
- `apps/backend` is a standalone Node server with a routes plugin, auth/error plugins, DB migrations.
- `apps/infra` contains Pulumi code to define k8s resources (Ingress, Services, PVCs, Secrets) and Vultr VKE.

##### README insights
- Each app is deployed as a Docker container into Kubernetes via Pulumi.
- Primary data store: Airtable (closed source), sometimes Postgres.
- Auth: Keycloak (`apps/login`) with an account‐proxy. JWT/OIDC flows.
- Proxies: nginx reverse proxies (`website-proxy`, `posthog-proxy`, `miniextensions-proxy`) to route traffic & handle migrations.
- CI/CD: GitHub Actions for build, test, CD; `libraries/docker-scripts` for multi-stage deploy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    User["End Users (Browser/Mobile)"]:::external
    BubbleAirtable["Bubble/Airtable Integrations"]:::external
    ZoomSDK["Zoom Web SDK"]:::external
    PostHogSaaS["PostHog SaaS"]:::external

    %% Edge / Ingress & Proxies
    subgraph "Edge / Ingress & Proxies"
        direction TB
        Ingress["Ingress Controller (k8s)"]:::infra
        WP["website-proxy"]:::proxy
        PP["posthog-proxy"]:::proxy
        MP["miniextensions-proxy"]:::proxy
        LAP["login-account-proxy"]:::proxy
    end

    %% Authentication Service
    subgraph "Authentication"
        direction TB
        Keycloak["Keycloak OIDC Service"]:::auth
    end

    %% Frontend Apps
    subgraph "Frontend Apps"
        direction TB
        Website["Website (Next.js)"]:::frontend
        Availability["Availability (Next.js)"]:::frontend
        Meet["Meet (Next.js + Zoom SDK)"]:::frontend
        CourseDemos["Course Demos (Next.js)"]:::frontend
        Editor["Editor (Next.js)"]:::frontend
        Room["Room Display (Next.js)"]:::frontend
        FEExample["Frontend Example (Next.js)"]:::frontend
        Storybook["Storybook (UI Explorer)"]:::frontend
    end

    %% API / Backends
    subgraph "API / Backends"
        direction TB
        API_Routes["Next.js API Routes"]:::backend
        BackendNode["backend (Node.js)"]:::backend
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        Airtable["Airtable"]:::database
        Postgres["Postgres Cluster"]:::database
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        UILib["libraries/ui"]:::shared
        BackendContract["libraries/backend-contract"]:::shared
        DockerScripts["libraries/docker-scripts"]:::shared
        ESLintConfig["libraries/eslint-config"]:::shared
        ESLintPlugin["libraries/eslint-plugin-custom"]:::shared
        TSConfig["libraries/typescript-config"]:::shared
        Affected["libraries/affected-packages"]:::shared
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        direction TB
        Pulumi["apps/infra (Pulumi IaC)"]:::infra
        GitHubActions["GitHub Actions CI/CD"]:::infra
        Turbo["turbo.json"]:::infra
    end

    %% Flows
    User --> Ingress
    Ingress --> WP
    Ingress --> PP
    Ingress --> MP
    Ingress --> LAP

    WP --> Website
    WP --> Availability
    WP --> Meet
    WP --> CourseDemos
    WP --> Editor
    WP --> Room
    WP --> FEExample
    WP --> Storybook

    Website --> API_Routes
    Availability --> API_Routes
    Meet --> API_Routes
    CourseDemos --> API_Routes
    Editor --> API_Routes
    Room --> API_Routes
    FEExample --> API_Routes

    API_Routes --> Airtable
    API_Routes --> Postgres

    Availability --> Airtable
    Meet --> ZoomSDK
    CourseDemos --> BubbleAirtable
    Storybook --> UILib

    User -->|Login Redirect| Keycloak
    Keycloak -->|JWT| Website
    Keycloak -->|JWT| API_Routes

    API_Routes --> BackendNode
    BackendNode --> Postgres

    Website --> PP
    API_Routes --> PP
    PP --> PostHogSaaS

    %% Shared Libraries imports
    Website --> UILib
    Availability --> UILib
    Meet --> UILib
    CourseDemos --> UILib
    Editor --> UILib
    FEExample --> UILib
    BackendNode --> BackendContract
    Website --> DockerScripts
    BackendNode --> DockerScripts
    Pulumi --> DockerScripts

    GitHubActions --> DockerScripts
    GitHubActions --> Pulumi
    GitHubActions --> Website
    GitHubActions --> BackendNode

    Turbo --> UILib
    Turbo --> BackendContract
    Turbo --> DockerScripts
    Turbo --> ESLintConfig
    Turbo --> ESLintPlugin
    Turbo --> TSConfig
    Turbo --> Affected

    %% Click Events
    click WP "https://github.com/bluedotimpact/bluedot/tree/master/apps/website-proxy"
    click PP "https://github.com/bluedotimpact/bluedot/tree/master/apps/posthog-proxy"
    click MP "https://github.com/bluedotimpact/bluedot/tree/master/apps/miniextensions-proxy"
    click LAP "https://github.com/bluedotimpact/bluedot/tree/master/apps/login-account-proxy"
    click Keycloak "https://github.com/bluedotimpact/bluedot/tree/master/apps/login"
    click Website "https://github.com/bluedotimpact/bluedot/tree/master/apps/website"
    click Availability "https://github.com/bluedotimpact/bluedot/tree/master/apps/availability"
    click Meet "https://github.com/bluedotimpact/bluedot/tree/master/apps/meet"
    click CourseDemos "https://github.com/bluedotimpact/bluedot/tree/master/apps/course-demos"
    click Editor "https://github.com/bluedotimpact/bluedot/tree/master/apps/editor"
    click Room "https://github.com/bluedotimpact/bluedot/tree/master/apps/room"
    click FEExample "https://github.com/bluedotimpact/bluedot/tree/master/apps/frontend-example"
    click Storybook "https://github.com/bluedotimpact/bluedot/tree/master/apps/storybook"
    click BackendNode "https://github.com/bluedotimpact/bluedot/tree/master/apps/backend"
    click UILib "https://github.com/bluedotimpact/bluedot/tree/master/libraries/ui"
    click BackendContract "https://github.com/bluedotimpact/bluedot/tree/master/libraries/backend-contract"
    click DockerScripts "https://github.com/bluedotimpact/bluedot/tree/master/libraries/docker-scripts"
    click ESLintConfig "https://github.com/bluedotimpact/bluedot/tree/master/libraries/eslint-config"
    click ESLintPlugin "https://github.com/bluedotimpact/bluedot/tree/master/libraries/eslint-plugin-custom"
    click TSConfig "https://github.com/bluedotimpact/bluedot/tree/master/libraries/typescript-config"
    click Affected "https://github.com/bluedotimpact/bluedot/tree/master/libraries/affected-packages"
    click Pulumi "https://github.com/bluedotimpact/bluedot/tree/master/apps/infra"
    click GitHubActions "https://github.com/bluedotimpact/bluedot/blob/master/.github/workflows/ci_cd.yaml"
    click Turbo "https://github.com/bluedotimpact/bluedot/blob/master/turbo.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#DFF4DD,stroke:#228B22,color:#228B22
    classDef proxy fill:#FFEDD5,stroke:#FF8C00,color:#FF8C00
    classDef auth fill:#FFE4E1,stroke:#DC143C,color:#DC143C
    classDef database fill:#EDE5FF,stroke:#6A0DAD,color:#6A0DAD
    classDef shared fill:#F0F0F0,stroke:#666666,color:#333333
    classDef infra fill:#F5F5F5,stroke:#A9A9A9,color:#333333
    classDef external fill:none,stroke-dasharray: 5 5,stroke:#999999,color:#999999
```
