# orcasound/orcanode architecture

> Architecture diagram of the GitHub repository orcasound/orcanode, 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/orcanode
- Repository: https://github.com/orcasound/orcanode

## Overview

##### Main Components

a. Hardware Layer:
- Sound Input Devices (Hydrophones)
- Computing Platforms (Raspberry Pi/AMD64 systems)
- Sound Cards (e.g., Pisound HAT)

b. Container Infrastructure:
- Docker containers for different services
- Base images for different architectures (ARM32v7, AMD64)

c. Audio Processing Pipeline:
- Audio Capture (ALSA/Jack)
- FFmpeg Processing
- File Generation Systems

d. Storage Systems:
- Local Storage (/tmp and /mnt directories)
- Cloud Storage (AWS S3 buckets)

e. Monitoring & Logging:
- LogDNA integration
- System monitoring

**[Hardware Layer]**
- ↓
**[Container Layer]**
- ↓
**[Audio Processing]**
- ↓
**[Storage Layer]**
- ↓
**[Monitoring Layer]**

##### Key Relationships

- Data Flow:
- Audio input → FFmpeg processing
- Processed audio → Local storage
- Local storage → S3 bucket synchronization
- System logs → LogDNA

- Component Integration:
- Docker container relationships
- Storage system interactions
- Monitoring system connections

##### Technical Details

- FFmpeg pipeline configuration
- AWS S3 integration points
- Docker container relationships
- Audio format conversion paths

##### The monitoring and logging infrastructure

Use standardized symbols:
- Rectangles for processing components
- Hexagons for input/output points
- Clouds for external services

This system design should capture both the current implementation and allow for future expansions, such as new audio format support or additional node types.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Hardware Layer
    subgraph Hardware
        H[Hydrophone]:::hardware
        SC[Sound Card]:::hardware
        CP[Computing Platform]:::hardware
    end

    %% Container Infrastructure Layer
    subgraph Containers
        direction TB
        BC[Base Container]:::container
        click BC "https://github.com/orcasound/orcanode/tree/master/base"
        
        subgraph Architectures
            direction TB
            AMD["AMD64 Base"]:::container
            ARM["ARM64 Base"]:::container
            RPI["RPi Base"]:::container
            click AMD "https://github.com/orcasound/orcanode/tree/master/base/amd64"
            click ARM "https://github.com/orcasound/orcanode/tree/master/base/arm64"
            click RPI "https://github.com/orcasound/orcanode/tree/master/base/rpi"
        end
        
        BC --> AMD & ARM & RPI
    end

    %% Audio Processing Layer
    subgraph Processing
        direction TB
        AS["Audio Source<br>(ALSA/Jack)"]:::processing
        
        subgraph StreamProcessing
            direction TB
            SS["Stream Setup"]:::processing
            click SS "https://github.com/orcasound/orcanode/blob/master/node/streamsetup.sh"
            
            SP["Stream Processing"]:::processing
            click SP "https://github.com/orcasound/orcanode/blob/master/node/stream.sh"
            
            SAMD["AMD64 Stream"]:::processing
            click SAMD "https://github.com/orcasound/orcanode/blob/master/node/streamamd64.sh"
            
            SRPI["RPi Stream"]:::processing
            click SRPI "https://github.com/orcasound/orcanode/blob/master/node/streamrpi.sh"
        end
        
        subgraph MSEEDProcessing
            direction TB
            MP["MSEED Processing"]:::processing
            click MP "https://github.com/orcasound/orcanode/tree/master/mseed"
            
            MPP["MSEED Pull"]:::processing
            click MPP "https://github.com/orcasound/orcanode/blob/master/mseed/mseedpull.py"
            
            OOI["OOI Integration"]:::processing
            click OOI "https://github.com/orcasound/orcanode/blob/master/mseed/ooipypull.py"
        end
    end

    %% Storage Layer
    subgraph Storage
        direction TB
        LS["Local Storage<br>(/tmp, /mnt)"]:::storage
        
        subgraph S3Storage
            direction TB
            S3U["S3 Upload"]:::storage
            click S3U "https://github.com/orcasound/orcanode/blob/master/base/upload_s3.py"
            
            S3F["FLAC S3 Upload"]:::storage
            click S3F "https://github.com/orcasound/orcanode/blob/master/base/upload_flac_s3.py"
        end
    end

    %% Docker Deployment
    subgraph Deployment
        direction TB
        DAMD["AMD64 Deployment"]:::deployment
        click DAMD "https://github.com/orcasound/orcanode/blob/master/node/docker-compose.amd64-build.yml"
        
        DARM["ARM64 Deployment"]:::deployment
        click DARM "https://github.com/orcasound/orcanode/blob/master/node/docker-compose.arm64-build.yml"
        
        DRPI["RPi Deployment"]:::deployment
        click DRPI "https://github.com/orcasound/orcanode/blob/master/node/docker-compose.rpi-build.yml"
    end

    %% Monitoring Layer
    subgraph Monitoring
        LDN["LogDNA"]:::monitoring
        SM["System Monitor"]:::monitoring
    end

    %% Connections
    H --> SC --> CP
    CP --> BC
    AS --> SP
    SP --> SAMD & SRPI
    SP --> MP
    MP --> MPP --> OOI
    SP --> LS --> S3U & S3F
    AMD --> DAMD
    ARM --> DARM
    RPI --> DRPI
    SP -.-> LDN & SM

    %% Styles
    classDef hardware fill:#b3d9ff,stroke:#333
    classDef container fill:#90EE90,stroke:#333
    classDef processing fill:#FFE5B4,stroke:#333
    classDef storage fill:#FFA07A,stroke:#333
    classDef deployment fill:#DDA0DD,stroke:#333
    classDef monitoring fill:#E6E6FA,stroke:#333

    %% Legend
    subgraph Legend
        L1["Hardware"]:::hardware
        L2["Container"]:::container
        L3["Processing"]:::processing
        L4["Storage"]:::storage
        L5["Deployment"]:::deployment
        L6["Monitoring"]:::monitoring
    end
```
