# dwn10/cs50_final_project architecture

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

- Interactive diagram: https://gitdiagram.com/dwn10/cs50_final_project
- Repository: https://github.com/dwn10/cs50_final_project

## Overview

##### Main Components
- Frontend/UI: Represented by the Streamlit interface that includes elements like custom HTML/JavaScript for geolocation and CSS for styling.
- Audio Recording Module: This includes the configuration for capturing live audio (using PyAudio and Wave) and the pre-recorded file handling.
- Processing & Search Engine: Where the system processes the audio input, applies filters, and constructs queries to search the external databases.
- External APIs and Data Sources: Include the four major integrated APIs:
– Xeno-canto API for bird recordings.
– Wikipedia API for detailed species information.
– eBird API for taxonomic classification.
– OpenStreetMap Nominatim for geolocation reverse lookup.

##### Relationships and Data Flow
- Inside the audio recording module, represent the process of buffering, processing, and converting audio to the required format (WAV).
- The processed audio flows into the Search Engine component, which then performs preprocessing (like normalization and validation) and applies filters (geographical, quality, and sound type) before constructing API queries.
- Finally, indicate the integration of all results back into the UI for display, including audio playback and detailed species information.

##### Architectural Patterns and Design Principles
- Modular design pattern where the audio processing, search filters, and external API interactions are separate modules.
- Separation of concerns by distinctly labeling frontend, backend processing, and API integrations.
- Optimizations (such as increased audio buffer size and caching strategies) that are mentioned in the README.
- Interaction style: synchronous data capture and processing with asynchronous data fetching from various APIs.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: Python (Streamlit), HTML5/JavaScript for geolocation, and CSS styling.
- Backend: Python 3.11+, PyAudio, Wave, NumPy, Requests.
- External: APIs from Xeno-canto, OpenStreetMap, Wikipedia, and eBird.
- Configuration approaches: Use of environment variables and Streamlit’s secrets management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User"):::user

    subgraph "Frontend Layer"
        UI["Streamlit UI (app.py)"]:::frontend
    end

    subgraph "Audio Processing Layer"
        Audio["Audio Recording Module (app.py)"]:::processing
        Proc["Processing & Search Engine (app.py)"]:::processing
    end

    subgraph "External Services"
        Xeno["Xeno-canto API"]:::external
        Wiki["Wikipedia API"]:::external
        Ebird["eBird API"]:::external
        OSM["OpenStreetMap API"]:::external
    end

    subgraph "Configuration Management"
        Config["Secrets & Environment (project/README.md)"]:::config
    end

    User -->|"starts"| UI
    UI -->|"captures_audio"| Audio
    Audio -->|"processes_audio"| Proc
    Proc -->|"queries"| Xeno
    Proc -->|"queries"| Wiki
    Proc -->|"queries"| Ebird
    Proc -->|"queries"| OSM
    Xeno -->|"returns_data"| Proc
    Wiki -->|"returns_data"| Proc
    Ebird -->|"returns_data"| Proc
    OSM -->|"returns_data"| Proc
    Proc -->|"delivers_results"| UI
    Config -->|"provides_credentials"| Proc

    click UI "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click Audio "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click Proc "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click Xeno "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click Wiki "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click Ebird "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click OSM "https://github.com/dwn10/cs50_final_project/blob/main/project/app.py"
    click Config "https://github.com/dwn10/cs50_final_project/blob/main/project/README.md"

    classDef user fill:#E0E0E0,stroke:#333,stroke-width:2px;
    classDef frontend fill:#f7c6c7,stroke:#333,stroke-width:2px;
    classDef processing fill:#c6f7d0,stroke:#333,stroke-width:2px;
    classDef external fill:#c6d9f7,stroke:#333,stroke-width:2px;
    classDef config fill:#f7f3c6,stroke:#333,stroke-width:2px;
```
