# mozzius/graysky architecture

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

- Interactive diagram: https://gitdiagram.com/mozzius/graysky
- Repository: https://github.com/mozzius/graysky

## Overview

##### Project type and purpose
- Graysky is a full-stack, monorepo-managed Bluesky client. It comprises:
- A React Native/Expo mobile app (`apps/expo`)
- A Next.js marketing/web app (`apps/nextjs`)
- A standalone Node.js push notification service (`apps/push-notifs`)
- Shared packages for internal API (`packages/api`) and database schema (`packages/db`)
- Utility scripts (cryptography), tooling configs, and container/orchestration files

##### File structure
- Top-level “apps” directories each encapsulate a deployable application or service.
- “packages/api” houses a tRPC router (gifs, translate) and is consumed by Next.js API routes.
- “packages/db” defines the Prisma schema for Postgres (or equivalent).
- “apps/push-notifs” is a microservice that subscribes to the Bluesky Firehose, persists subscriptions in the DB, and pushes to FCM/APNs.
- “cryptography/keyGen.py” is a helper for generating keys (e.g., APNs/FCM).
- Dockerfile, docker-compose.yml, and GitHub Actions YAML define container builds and CI pipeline.

##### README for insights
- Primary focus on building and running the Expo mobile client.
- Mentions push notifications (which maps to `apps/push-notifs`).

- Mobile Client (Expo/React Native)
- Web Client (Next.js)
- Internal tRPC API Service (packages/api)
- Push Notification Service (apps/push-notifs)
- Database (Prisma/Postgres from packages/db)
- External Bluesky PDS (app.bsky AT Protocol servers)
- External Services:
– Firebase Cloud Messaging (FCM) & Apple Push Notification service (APNs)
– Third-party APIs (GIF generation, translation)
- Mobile & Web → External PDS: authenticate & fetch Bluesky data via AT Protocol Agent
- Mobile & Web → Internal tRPC API: /api/trpc → packages/api router (for gifs & translate)
- Next.js hosts the tRPC API under `/api/trpc` using the shared router code
- Push-Notif Service subscribes to PDS Firehose stream → writes/reads tokens from Database → sends push messages to FCM/APNs
- Internal API & Push-Notif Service → Database (Prisma client)
- cryptography script → generates keys → used by Push-Notif Service
c. Architectural patterns & principles:
- Monorepo with pnpm & Turbo for fast builds & shared code
- Service-oriented: discrete deployable backends (Next.js serverless API, push service)
- Shared code via packages/api and packages/db
- React component hierarchy & hooks for mobile UI; Next.js Server Components for web
- tRPC for end-to-end typed APIs
- Prisma ORM for schema & migrations
d. Key technologies:
- Frontend: React Native (Expo), Next.js
- Backend: Node.js, tRPC, Prisma, Firehose client
- Deployment: Docker, docker-compose, EAS (Expo Application Services), GitHub Actions
- Package management: pnpm workspace, turborepo
- Internationalization: Crowdin & lingui

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        ExpoApp["Expo Mobile App"]:::frontend
        NextApp["Next.js Web App"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        subgraph "tRPC API Service"
            direction TB
            APIService["tRPC API Service"]:::backend
            RootRouter["root.ts"]:::backend
            GifsRouter["gifs.ts"]:::backend
            TranslateRouter["translate.ts"]:::backend
        end
        subgraph "Push Notification Service"
            direction TB
            PushService["Push-Notif Service"]:::backend
            FirehoseClient["firehose.ts"]:::backend
            DBClient["db.ts"]:::backend
            PushClient["push-notifications.ts"]:::backend
        end
        CryptoScript["keyGen.py"]:::tools
    end

    %% Data Layer
    subgraph "Data"
        direction TB
        Database[(Postgres Database)]:::data
        DBSchema["schema.prisma"]:::data
    end

    %% External Systems
    subgraph "External"
        direction TB
        BlueskyPDS["Bluesky PDS"]:::external
        FCM_APNs["FCM / APNs"]:::external
        ThirdPartyAPI["Third-Party APIs"]:::external
    end

    %% CI/CD & Deployment Tools
    subgraph "CI/CD & Deployment"
        direction TB
        Dockerfile["Dockerfile"]:::tools
        DockerCompose["docker-compose.yml"]:::tools
        CIConfig["ci.yml"]:::tools
    end

    %% Connections - Frontend to External and Backend
    ExpoApp -->|"AT Protocol Calls"| BlueskyPDS
    NextApp -->|"AT Protocol Calls"| BlueskyPDS
    ExpoApp -->|"/api/trpc"| APIService
    NextApp -->|"/api/trpc"| APIService

    %% Connections - Backend interactions
    APIService -->|Reads/Writes| Database
    PushService -->|Firehose Subscribe| BlueskyPDS
    PushService -->|Reads/Writes| Database
    PushService -->|Sends Push| FCM_APNs
    PushService -->|Invokes| CryptoScript
    APIService -->|Calls| ThirdPartyAPI

    %% Connections - Tools and CI/CD
    Dockerfile -->|Builds| ExpoApp
    Dockerfile -->|Builds| NextApp
    Dockerfile -->|Builds| PushService
    DockerCompose -->|Orchestrates| ExpoApp
    DockerCompose -->|Orchestrates| NextApp
    DockerCompose -->|Orchestrates| PushService
    CIConfig -->|Runs| Dockerfile
    CIConfig -->|Runs| DockerCompose

    %% Click Events
    click ExpoApp "https://github.com/mozzius/graysky/tree/main/apps/expo"
    click NextApp "https://github.com/mozzius/graysky/tree/main/apps/nextjs"
    click APIService "https://github.com/mozzius/graysky/blob/main/packages/api/src/root.ts"
    click RootRouter "https://github.com/mozzius/graysky/blob/main/packages/api/src/root.ts"
    click GifsRouter "https://github.com/mozzius/graysky/blob/main/packages/api/src/router/gifs.ts"
    click TranslateRouter "https://github.com/mozzius/graysky/blob/main/packages/api/src/router/translate.ts"
    click PushService "https://github.com/mozzius/graysky/blob/main/apps/push-notifs/src/index.ts"
    click FirehoseClient "https://github.com/mozzius/graysky/blob/main/apps/push-notifs/src/firehose.ts"
    click DBClient "https://github.com/mozzius/graysky/blob/main/apps/push-notifs/src/db.ts"
    click PushClient "https://github.com/mozzius/graysky/blob/main/apps/push-notifs/src/push-notifications.ts"
    click CryptoScript "https://github.com/mozzius/graysky/blob/main/cryptography/keyGen.py"
    click DBSchema "https://github.com/mozzius/graysky/blob/main/packages/db/prisma/schema.prisma"
    click Database "https://github.com/mozzius/graysky/blob/main/packages/db/index.ts"
    click Dockerfile "https://github.com/mozzius/graysky/tree/main/Dockerfile"
    click DockerCompose "https://github.com/mozzius/graysky/blob/main/docker-compose.yml"
    click CIConfig "https://github.com/mozzius/graysky/blob/main/.github/workflows/ci.yml.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#DFFFE0,stroke:#2F8F2F,color:#2F8F2F
    classDef data fill:#FFF5D0,stroke:#D69E00,color:#D69E00
    classDef external fill:#F0F0F0,stroke:#999999,color:#555555
    classDef tools fill:#F5E0FF,stroke:#884EA0,color:#884EA0
```
