# zakaria76al/usc architecture

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

- Interactive diagram: https://gitdiagram.com/zakaria76al/usc
- Repository: https://github.com/zakaria76al/usc

## Overview

##### Project type and purpose
- This is an open-source deep learning pipeline for underwater acoustic signal classification.
- It defines two neural network architectures (MFCC-based hybrid and end-to-end convolutional) and provides scripts for feature extraction, training, and inference.

##### File structure
Top-level files and folders:
- features.py – dataset loading & feature extraction module
- model.py – Keras model definitions (two architectures)
- params.py – hyperparameter and configuration container
- inference.py – script to run inference on a saved model
- requirements.txt – dependencies (e.g., TensorFlow/Keras, librosa)
- saved_models/ – zipped trained model archives
- weights/ – raw HDF5 model weights
- file.wav – sample input audio
- readme.md – project overview and results

Architectural hints
- A clear separation of concerns: data prep (features.py), model definition (model.py), configuration (params.py), and runtime inference (inference.py).
- Model artifacts are persisted in two forms: zipped archives (saved_models/) and HDF5 weights (weights/).

##### README for additional insights
- Confirms two architectures: “Hybrid” (MFCC + conv blocks) and “End-to-end” (raw signal input).
- Describes pipeline stages: feature extraction → model training → inference → performance evaluation.

a. Main components
1. Data Input
- Raw .wav files (e.g., file.wav) or dataset directories (DeepShip, ShipsEar).
2. Feature Extraction Module (features.py)
- Static MFCC extraction (hybrid model).
- Optional spectrogram generator for end-to-end.
3. Model Definition (model.py)
- Hybrid network architecture.
- End-to-end network architecture.
4. Configuration (params.py)
- Hyperparameters (learning rate, batch size, number of epochs, model type selector).
5. Training & Serialization
- Training process (Keras.fit).
- Save weights (.hdf5) and zipped models (.zip).
6. Model Storage
- weights/ directory
- saved_models/ directory
7. Inference Module (inference.py)
- Loads model architecture + weights.
- Takes file.wav or batch of files.
- Outputs classification results (labels, confidences).
8. Reporting & Results
- Console or file log of accuracy, precision, recall, F1.

b. Relationships and data flow
- Two parallel flows from Feature Extraction → Model Definition → Training.
- Outputs from Training → Model Storage.
- Inference Module loads from Model Storage and uses Model Definition.
- Inference Module → Reporting & Results.

c. Architectural patterns & principles
- Modular pipeline: each stage encapsulated in its own script.
- Separation of concerns between data prep, model logic, and inference.
- Reproducibility: parameters externalized in params.py, models versioned in storage directories.

d. Key technologies & libraries
- Python 3.x
- TensorFlow/Keras for DL
- librosa (or similar) for audio feature extraction
- HDF5 for weight serialization
- Zip archive for model packaging

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Modules"
        Requirements["dependencies\nrequirements.txt"]:::data
        Readme["project overview\nreadme.md"]:::docs
        Input["file.wav"]:::data
    end

    subgraph "Preprocessing"
        Features["Feature Extraction Module\nfeatures.py"]:::processing
    end

    subgraph "Modeling & Training"
        Params["Configuration\nparams.py"]:::orchestration
        ModelDef["Model Definition\nmodel.py"]:::processing
        Training["Training & Serialization"]:::orchestration
    end

    subgraph "Model Storage"
        SavedModels[(saved_models/)]:::storage
        Weights[(weights/)]:::storage
    end

    subgraph "Inference & Reporting"
        Inference["Inference Module\ninference.py"]:::processing
        Reporting["Reporting & Results"]:::docs
    end

    %% Data flow
    Input --> Features
    Features --> ModelDef
    Params --> ModelDef
    ModelDef --> Training
    Training --> SavedModels
    Training --> Weights
    SavedModels --> Inference
    Weights --> Inference
    Params --> Inference
    Input --> Inference
    Inference --> Reporting

    %% Click events
    click Input "https://github.com/zakaria76al/usc/blob/main/file.wav"
    click Features "https://github.com/zakaria76al/usc/blob/main/features.py"
    click ModelDef "https://github.com/zakaria76al/usc/blob/main/model.py"
    click Params "https://github.com/zakaria76al/usc/blob/main/params.py"
    click Training "https://github.com/zakaria76al/usc/blob/main/model.py"
    click SavedModels "https://github.com/zakaria76al/usc/tree/main/saved_models/"
    click Weights "https://github.com/zakaria76al/usc/tree/main/weights/"
    click Inference "https://github.com/zakaria76al/usc/blob/main/inference.py"
    click Requirements "https://github.com/zakaria76al/usc/blob/main/requirements.txt"
    click Readme "https://github.com/zakaria76al/usc/blob/main/readme.md"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef processing fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef orchestration fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef storage fill:#D1C4E9,stroke:#8E24AA,color:#4A148C
    classDef docs fill:#CFD8DC,stroke:#607D8B,color:#37474F
```
