# yajanarao/serenity architecture

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

- Interactive diagram: https://gitdiagram.com/yajanarao/serenity
- Repository: https://github.com/yajanarao/serenity

## Overview

##### Project type and purpose
- This is a client-heavy, monorepo multimedia application (called “Serenity”) that delivers audio content (music, meditation, podcasts) on two platforms:
- A React Native mobile app (Android & iOS) under apps/mobile
- A React web app under apps/web
- It leverages a modular architecture with shared UI components (packages/components), core state management logic (packages/core), and extension plugins (packages/extensions)
- It uses Supabase as its backend (authentication, database, storage), plus external APIs (e.g., YouTube for streaming)

##### File structure
- Top-level directories
- apps/mobile → full React Native codebase (Java/Kotlin for Android, Objective-C/Swift for iOS, plus JS/TS business logic)
- apps/web → React single-page application
- packages/components → shared UI React( Native ) components
- packages/core → Redux slices, hooks, store setup—shared domain logic
- packages/extensions → plugin implementations for streaming sources (YouTube, JioSaavn, etc.)
- scripts, docs, CI/CD configs (GitHub Actions, Travis, Fastlane)
- The monorepo is orchestrated by Turbo/Turborepo (turbo.json) and Yarn Workspaces (package.json at root)
- No proprietary backend code lives here—Supabase config is in apps/mobile/src/services/supabase.ts; apps talk directly to Supabase

##### README for additional insights
- Confirms cross-platform focus, streaming from local & online, plugin-based audio sources, voice search
- Points to docs/Setup.md for environment and deployment, and to Supabase as the sole backend

##### Main components
a. User Devices and Applications
- Mobile App (Android & iOS)
- Web App (Browser)
b. Shared Monorepo Packages
- UI Component Library (packages/components)
- Core State & Business Logic (packages/core)
- Extensions/Plugins (packages/extensions)
c. Backend & External Services
- Supabase (Auth, PostgreSQL DB, Storage)
- External Streaming APIs (YouTube Data API, JioSaavn, etc.)
- Voice Search Service (e.g., device microphone → speech recognition API)

##### Relationships and interactions
- Mobile/Web App UIs import & render components from packages/components
- UIs dispatch actions to the Redux store in packages/core
- Core logic invokes Supabase client SDK (direct HTTP/WebSocket) for user auth, data fetch/store
- Core logic also loads extensions from packages/extensions to fetch online audio streams
- UIs handle voice search by calling a speech-to-text service, then querying core/search plugins
- CI/CD pipelines (GitHub Actions + Fastlane) build & deploy mobile apps; Netlify/Vercel or similar builds the web app

##### Architectural patterns & design principles
- Monorepo with clear separation between front-ends, shared UI, domain logic, and plugins
- Modular plugin architecture: new audio sources are added under packages/extensions without touching core
- Redux pattern (slices, store) isolated in packages/core, ensuring consistent state management across platforms
- Component-driven design: packages/components provides cross-platform building blocks
- Direct-to-Backend approach: no custom server; clients talk to Supabase & third-party APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Applications Layer
    MobileApp["📱 Mobile App (React Native)"]:::app
    WebApp["🌐 Web App (React SPA)"]:::app

    %% Monorepo Codebase
    subgraph "Monorepo / Codebase"
        direction TB
        UIComponents["UI Component Library"]:::ui
        CoreLogic["Core State & Business Logic"]:::core
        Extensions["Extensions / Plugins"]:::ext
        Turbo["Turborepo Orchestration"]:::orchestration
        YarnWorkspaces["Yarn Workspaces"]:::orchestration
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Supabase["Supabase (Auth, DB, Storage)"]:::external
        YouTubeAPI["YouTube Data API"]:::external
        JioSaavnAPI["JioSaavn API"]:::external
        SpeechService["Speech-to-Text Service"]:::external
    end

    %% CI/CD Processes
    subgraph "CI/CD & Deployment"
        direction TB
        GHProd["GitHub Actions - Production"]:::ci
        GHStaging["GitHub Actions - Staging"]:::ci
        Fastlane["Fastlane Mobile Deployment"]:::ci
    end

    %% Relationships
    MobileApp -->|imports| UIComponents
    WebApp    -->|imports| UIComponents
    UIComponents -->|dispatch actions| CoreLogic
    CoreLogic -->|auth & data| Supabase
    CoreLogic -->|load plugins| Extensions
    Extensions -->|stream| YouTubeAPI
    Extensions -->|stream| JioSaavnAPI
    MobileApp -->|voice input| SpeechService
    SpeechService -->|text query| CoreLogic

    %% CI/CD Arrows
    GHProd -->|build/deploy| MobileApp
    GHStaging -->|build/deploy| WebApp
    Fastlane -->|deploy| MobileApp

    %% Monorepo Orchestration Links
    Turbo --> UIComponents
    Turbo --> CoreLogic
    Turbo --> Extensions
    YarnWorkspaces --> UIComponents
    YarnWorkspaces --> CoreLogic
    YarnWorkspaces --> Extensions

    %% Click Events
    click MobileApp "https://github.com/yajanarao/serenity/tree/develop/apps/mobile"
    click WebApp "https://github.com/yajanarao/serenity/tree/develop/apps/web"
    click UIComponents "https://github.com/yajanarao/serenity/tree/develop/packages/components"
    click CoreLogic "https://github.com/yajanarao/serenity/tree/develop/packages/core"
    click Extensions "https://github.com/yajanarao/serenity/tree/develop/packages/extensions"
    click Supabase "https://github.com/yajanarao/serenity/blob/develop/apps/mobile/src/services/supabase.ts"
    click GHProd "https://github.com/yajanarao/serenity/blob/develop/.github/workflows/production.yml"
    click GHStaging "https://github.com/yajanarao/serenity/blob/develop/.github/workflows/staging.yml"
    click Fastlane "https://github.com/yajanarao/serenity/tree/develop/apps/mobile/fastlane/Fastfile"
    click Turbo "https://github.com/yajanarao/serenity/blob/develop/turbo.json"
    click YarnWorkspaces "https://github.com/yajanarao/serenity/blob/develop/package.json"

    %% Styles
    classDef app fill:#f9f,stroke:#333,stroke-width:2px;
    classDef ui fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef ext fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef external fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
    classDef orchestration fill:#eeeeee,stroke:#757575,stroke-width:2px,stroke-dasharray: 5 5;
    classDef ci fill:#f5f5f5,stroke:#616161,stroke-width:2px,stroke-dasharray: 3 3;
```
