# orcasound/orcasite architecture

> Architecture diagram of the GitHub repository orcasound/orcasite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orcasound/orcasite
- Repository: https://github.com/orcasound/orcasite

## Overview

##### Main Components

a. Frontend Layer:
- Next.js application (ui/ directory)
- Components for audio player, detection system, and user interface
- GraphQL client for data fetching
- WebSocket connections for real-time updates

b. Backend Layer:
- Phoenix Framework (server/ directory)
- GraphQL API endpoint
- WebSocket channels for real-time communication
- Authentication system
- JSON API endpoints

c. Database Layer:
- PostgreSQL with PostGIS extension
- Multiple data models (feeds, detections, users, notifications)

d. External Services:
- Audio streaming service
- AWS services (indicated by AWS client in radio/)
- Email service (via mailer component)

**[Client Layer]**

- Next.js Frontend (Port 3000)
- Audio Player Components
- Real-time Updates (WebSocket)
- GraphQL Client
- User Interface Components

- [API Layer]

- ┴─────────────────────┐

- Phoenix Backend (Port 4000)          │
- GraphQL API                       │
- JSON API                          │
- WebSocket Channels                │
- Authentication                    │
- Business Logic                    │

- [Service Layer]                │

- ┴────────────────┐      │

- ┌─ Audio Processing ─┐          │      │
- Spectrogram    │          │      │
- Feed Segments  │          │      │
- ┘          │      │

- ┌─ Notification System ─┐     │      │
- Email             │     │      │
- Subscriptions     │     │      │
- ┘     │      │

- ┘      │

- [Storage Layer]                   │

- ┌───────────┴───────────┐              │

- PostgreSQL + PostGIS │              │
- Feeds            │              │
- Detections       │              │
- Users           │              │
- Notifications   │              │

- ┘              │

- [External Services] │

- ┴────────────┘

- ┌────────┴─────────┐

- AWS Services        Email Service

##### Important Relationships to Highlight
- WebSocket connections between frontend and backend for real-time updates
- GraphQL/JSON API communication paths
- Database interactions
- External service integrations
- Authentication flow

##### Additional Elements
- Data flow direction indicators
- Scalability points
- Security boundaries
- Deployment environments (development/production)

##### Technical Details
- Port numbers (3000 for UI, 4000 for API)
- Database extensions (PostGIS)
- Key technologies (Elixir, Phoenix, Next.js)
- Authentication mechanisms
- API protocols (GraphQL, JSON API, WebSocket)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        UI[Next.js Frontend]
        AC[Audio Player Components]
        GC[GraphQL Client]
        WS[WebSocket Integration]
        UI --> AC
        UI --> GC
        UI --> WS
    end

    subgraph Backend
        PF[Phoenix Framework]
        GQL[GraphQL API]
        WSC[WebSocket Channels]
        Auth[Authentication System]
        JSON[JSON API]
        PF --> GQL
        PF --> WSC
        PF --> Auth
        PF --> JSON
    end

    subgraph Services
        AP[Audio Processing]
        NS[Notification System]
        RT[Real-time Presence]
        RS[Radio Service]
        AWS[AWS Integration]
        ES[Email Service]
    end

    subgraph Database
        DB[(PostgreSQL + PostGIS)]
        FM[Feed Model]
        DM[Detection Model]
        UM[User Model]
        NM[Notification Model]
        SM[Subscription Model]
        LM[Location Model]
        TM[Tag Model]
        DB --> FM
        DB --> DM
        DB --> UM
        DB --> NM
        DB --> SM
        DB --> LM
        DB --> TM
    end

    UI --> PF
    WS --> WSC
    GC --> GQL
    PF --> Services
    Services --> DB

    classDef frontend fill:#3498db
    classDef backend fill:#2ecc71
    classDef service fill:#e74c3c
    classDef database fill:#f1c40f

    class UI,AC,GC,WS frontend
    class PF,GQL,WSC,Auth,JSON backend
    class AP,NS,RT,RS,AWS,ES service
    class DB,FM,DM,UM,NM,SM,LM,TM database

    click UI "https://github.com/orcasound/orcasite/tree/main/ui/"
    click AC "https://github.com/orcasound/orcasite/tree/main/ui/src/components/Player/"
    click GC "https://github.com/orcasound/orcasite/blob/main/ui/src/graphql/client.ts"
    click WS "https://github.com/orcasound/orcasite/blob/main/ui/src/utils/socket.ts"
    click PF "https://github.com/orcasound/orcasite/tree/main/server/lib/orcasite/"
    click GQL "https://github.com/orcasound/orcasite/tree/main/server/lib/orcasite_web/graphql/"
    click WSC "https://github.com/orcasound/orcasite/tree/main/server/lib/orcasite_web/channels/"
    click Auth "https://github.com/orcasound/orcasite/tree/main/server/lib/orcasite_web/auth/"
    click JSON "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite_web/json_api_router.ex"
    click DB "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite/repo.ex"
    click FM "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite/radio/feed.ex"
    click DM "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite/radio/detection.ex"
    click UM "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite/accounts/user.ex"
    click AWS "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite/radio/aws_client.ex"
    click ES "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite/mailer.ex"
    click AP "https://github.com/orcasound/orcasite/blob/main/server/audio_viz/core/spectrogram_generator.py"
    click NS "https://github.com/orcasound/orcasite/tree/main/server/lib/orcasite/notifications/"
    click RT "https://github.com/orcasound/orcasite/blob/main/server/lib/orcasite_web/channels/presence.ex"
    click RS "https://github.com/orcasound/orcasite/tree/main/server/lib/orcasite/radio/"
```
