# sanjanavarade/nexora architecture

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

- Interactive diagram: https://gitdiagram.com/sanjanavarade/nexora
- Repository: https://github.com/sanjanavarade/nexora

## Overview

##### Project Type and Purpose
- This is a full-stack, live-streaming platform built on Next.js 14 (App Router).
- It provides public browsing (“browse”), creator dashboards (“dashboard”), auth flows, real-time chat, RTMP/WHIP ingestion, webhooks, and a Postgres + Prisma backend.

##### File-Structure Analysis
- Top-level “app” folder subdivided into:
– (auth): registration + sign-in pages (Server Components + layouts)
– (browse): public/home and user profile browsing UI
– (dashboard): protected creator UI (home, chat, keys)
– api/: Route Handlers for auth ([...nextauth]), webhooks, stream token & lifecycle
- “components” contains shared UI (shadcn/ui, stream-player, theme provider).
- “lib” holds backend service modules (auth-service, stream-service, user-service, follow-service, block-service, recommended-service).
- “prisma” holds schema and migrations for PostgreSQL.
- “hooks” and “store” contain client hooks for viewer tokens and sidebar state.
- Configuration: next.config.ts, middleware.ts, tailwind/postcss configs, env vars.

##### README Insights
- Technology stack: Next.js (frontend + API), TypeScript, Tailwind, Prisma + PostgreSQL, NextAuth, OBS → RTMP/WHIP.
- Features: live broadcasting, auth, channel mgmt, real-time chat (WebSocket/SSE ready), stream lifecycle webhooks, local tunnels (ngrok).
- Deployment: Vercel for frontend & API, optional Railway/Render/Fly.io for media server.

##### Main Components & Interactions
a. Client Layer
- Web Browsers: React UI (Next.js App Router)
- OBS (or WHIP-enabled client): publishes stream via RTMP/WHIP
b. Edge/API Layer (Next.js)
- Route Handlers under app/api → handle auth, stream token issuance, start/stop calls, webhooks, follow/block actions
- Server Components (layouts/pages) for auth, browse, dashboard
- Middleware for auth checks (protect dashboard routes)
c. Business-Logic Services (lib/*.ts)
- auth-service, user-service → user lookup, session mgmt (NextAuth + Prisma adapter)
- stream-service → create token, update isLive, viewers count
- block-service, follow-service, recommended-service → community features
d. Database Layer
- PostgreSQL with Prisma Client (schema.prisma) → models: User, Channel, Stream, ChatMessage, Account, Session, VerificationToken
e. Real-Time & External Services
- Media-ingest server (Node Media Server or NGINX RTMP or cloud RTMP)
- Chat transport (WebSocket or SSE channel—planned)
- Webhooks: media server calls /api/webhooks on start/stop, auth via WEBHOOK_SECRET
- Tunnels (ngrok/Cloudflared) for local testing

##### Architectural Patterns & Principles
- “BFF” pattern: Next.js acts as both frontend and backend for data gathering, composition, and SSR/SSR.
- App-Router grouping for layout isolation (auth vs. public vs. protected).
- Service-layer abstraction in lib/ for business rules and DB operations.
- Prisma Migrations for schema evolution.
- Environment-driven configuration for secrets, URLs, streaming endpoints.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients Layer
    subgraph "Clients"
        VB["Viewer Browser"]:::frontend
        OBS["OBS/WHIP Publisher"]:::streaming
    end

    %% Next.js Server Layer
    subgraph "Next.js Server (App Router & API)"
        %% UI - App Router
        subgraph "Auth (app/(auth))"
            AuthLayout["Auth Layout"]:::frontend
            SignInPage["Sign-In Page"]:::frontend
            SignUpPage["Sign-Up Page"]:::frontend
        end

        subgraph "Browse (app/(browse))"
            BrowseLayout["Browse Layout"]:::frontend
            BrowseHome["Browse Home"]:::frontend
            BrowseUser["User Profile"]:::frontend
        end

        subgraph "Dashboard (app/(dashboard))"
            DashLayout["Dashboard Layout"]:::frontend
            DashHome["Dashboard Home"]:::frontend
            DashChat["Dashboard Chat"]:::frontend
            DashKeys["Dashboard Keys"]:::frontend
        end

        %% API Route Handlers
        subgraph "API Route Handlers (app/api)"
            AuthAPI["NextAuth API"]:::api
            WebhookAPI["Webhooks API"]:::api
            LivekitWebhookAPI["Livekit Webhooks"]:::api
            StreamTokenAPI["Stream Token API"]:::api
            StreamLifecycleAPI["Stream Lifecycle API"]:::api
            FollowAPI["Follow API"]:::api
            BlockAPI["Block API"]:::api
        end

        Middleware["middleware.ts"]:::api

        %% Business Services
        subgraph "Business Services (lib)"
            AuthService["auth-service.ts"]:::api
            UserService["user-service.ts"]:::api
            StreamService["stream-service.ts"]:::api
            FollowService["follow-service.ts"]:::api
            BlockService["block-service.ts"]:::api
            RecService["recommended-service.ts"]:::api
            PrismaClient["prisma.ts"]:::api
        end
    end

    %% Data & External Layer
    subgraph "Data & External"
        Postgres["Postgres (Prisma)"]:::db
        PrismaSchema["schema.prisma"]:::db
        Migrations["migrations/*"]:::db
        StreamServer["RTMP/WHIP Ingest"]:::streaming
        WebhookProd["Media Server Webhook"]:::external
        Ngrok["ngrok.exe"]:::external
        ChatTransport["WebSocket/SSE"]:::external
    end

    %% Data Flows
    OBS -->|"RTMP/WHIP"| StreamServer
    StreamServer -->|onStart/onStop| WebhookProd
    WebhookProd -->|POST /api/webhooks| WebhookAPI
    WebhookAPI -->|update| StreamService
    StreamService -->|UPDATE isLive, viewers| Postgres

    VB -->|navigates| AuthLayout
    VB -->|navigates| BrowseLayout
    VB -->|protected| DashLayout
    AuthLayout -->|calls /api/auth| AuthAPI
    AuthAPI -->|uses| AuthService
    AuthService -->|reads/writes| PrismaClient
    PrismaClient -->|queries| Postgres

    VB -->|GET pages| BrowseHome
    VB -->|GET pages| BrowseUser
    BrowseLayout -->|components| BrowseHome
    BrowseLayout -->|components| BrowseUser

    VB -->|GET pages| DashHome
    VB -->|GET pages| DashChat
    VB -->|GET pages| DashKeys
    DashLayout -->|components| DashHome
    DashLayout -->|components| DashChat
    DashLayout -->|components| DashKeys

    VB -->|calls| StreamTokenAPI
    StreamTokenAPI --> StreamService
    VB -->|calls| FollowAPI
    FollowAPI --> FollowService
    VB -->|calls| BlockAPI
    BlockAPI --> BlockService
    VB -->|subscribes| ChatTransport
    ChatTransport -->|events| VB

    Middleware -->|protects| DashLayout
    Middleware --> AuthAPI

    AuthService --> UserService
    UserService --> PrismaClient
    FollowService --> PrismaClient
    BlockService --> PrismaClient
    RecService --> PrismaClient

    PrismaSchema --> Postgres
    Migrations --> Postgres

    %% Click Events
    click AuthLayout "https://github.com/sanjanavarade/nexora/blob/main/app/(auth)/layout.tsx"
    click SignInPage "https://github.com/sanjanavarade/nexora/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
    click SignUpPage "https://github.com/sanjanavarade/nexora/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.tsx"

    click BrowseLayout "https://github.com/sanjanavarade/nexora/blob/main/app/(browse)/layout.tsx"
    click BrowseHome "https://github.com/sanjanavarade/nexora/blob/main/app/(browse)/page.tsx"
    click BrowseHome "https://github.com/sanjanavarade/nexora/blob/main/app/(browse)/(home)/page.tsx"
    click BrowseUser "https://github.com/sanjanavarade/nexora/blob/main/app/(browse)/[username]/page.tsx"

    click DashLayout "https://github.com/sanjanavarade/nexora/blob/main/app/(dashboard)/u/[username]/layout.tsx"
    click DashHome "https://github.com/sanjanavarade/nexora/blob/main/app/(dashboard)/u/[username]/(home)/page.tsx"
    click DashChat "https://github.com/sanjanavarade/nexora/blob/main/app/(dashboard)/u/[username]/chat/page.tsx"
    click DashKeys "https://github.com/sanjanavarade/nexora/blob/main/app/(dashboard)/u/[username]/keys/page.tsx"

    click WebhookAPI "https://github.com/sanjanavarade/nexora/blob/main/app/api/webhooks/route.ts"
    click LivekitWebhookAPI "https://github.com/sanjanavarade/nexora/blob/main/app/api/webhooks/livekit/route.ts"

    click AuthService "https://github.com/sanjanavarade/nexora/blob/main/lib/auth-service.ts"
    click UserService "https://github.com/sanjanavarade/nexora/blob/main/lib/user-service.ts"
    click StreamService "https://github.com/sanjanavarade/nexora/blob/main/lib/stream-service.ts"
    click FollowService "https://github.com/sanjanavarade/nexora/blob/main/lib/follow-service.ts"
    click BlockService "https://github.com/sanjanavarade/nexora/blob/main/lib/block-service.ts"
    click RecService "https://github.com/sanjanavarade/nexora/blob/main/lib/recommended-service.ts"
    click PrismaClient "https://github.com/sanjanavarade/nexora/blob/main/lib/prisma.ts"

    click PrismaSchema "https://github.com/sanjanavarade/nexora/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/sanjanavarade/nexora/tree/main/prisma/migrations/*"

    click Middleware "https://github.com/sanjanavarade/nexora/blob/main/middleware.ts"
    click Ngrok "https://github.com/sanjanavarade/nexora/blob/main/ngrok.exe"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#3B82F6,color:#1E40AF
    classDef api fill:#D1FAE5,stroke:#10B981,color:#064E3B
    classDef db fill:#FEF3C7,stroke:#F59E0B,color:#92400E
    classDef streaming fill:#FEE2E2,stroke:#EF4444,color:#7F1D1D
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#374151
```
