# youssef-rahmouni/vocalrecovery architecture

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

- Interactive diagram: https://gitdiagram.com/youssef-rahmouni/vocalrecovery
- Repository: https://github.com/youssef-rahmouni/vocalrecovery

## Overview

##### Project type and purpose
- Vocal-Recovery is a small, open-source Python CLI tool whose sole purpose is to recover and extract audio recordings from arbitrary file system locations by scanning metadata (duration, size, date, optional keywords).
- It is not a web app or microservice: it’s a single-process command-line utility with a clear focus on file I/O and metadata filtering.

##### File structure
- Top-level scripts:
- main.py – the entry point that parses user choices (Auto vs Manual), invokes the core logic, and orchestrates I/O.
- tools.py – houses the core functions for scanning directories, reading metadata, applying filters, and copying matched files.
- Data/config:
- CallsList.csv – example CSV input for Auto Search mode (drives batch criteria).
- Supporting directories:
- others/legacys and others/ToDo – legacy code and backlog items (not part of runtime).
- tests/ – unit tests across three levels (test_lvl0.py, testlvl1.py, testlvl2.py).
- out_record/items_finds/ – the runtime output folder where matched audio files are placed.

##### README for additional insights
- Describes two modes (Auto vs Manual) and the end-to-end flow: user chooses mode → tool scans file system → filters by metadata → copies matches into out_record.
- Mentions future features tracked in ToDo.
- No explicit external service dependencies; uses local Python libs to read metadata and copy files.

##### Elements
- Blue for user-facing components (CLI, msg.py)
- Green for business logic (tools.py)
- Orange for data sources/sinks (file system, CSV)
- Gray for tests and legacy/backlog modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    main["main.py"]:::cli
    msg["msg.py"]:::ui
    tools["tools.py"]:::logic

    %% Data Sources
    FS["File System Audio Dirs"]:::data
    CSV["CallsList.csv"]:::data
    Manual["Manual Input Parameters"]:::data

    %% Output Sink
    Output["out_record/items_finds/"]:::sink

    %% Development Artifacts
    subgraph "Development Artifacts"
        direction TB
        test0["test/test_lvl0.py"]:::dev
        test1["test/testlvl1.py"]:::dev
        test2["test/testlvl2.py"]:::dev
        othersLegacy["others/legacys"]:::dev
        othersTodo["others/ToDo"]:::dev
    end

    %% Runtime Flow
    main -->|"display_UI"| msg
    msg -->|"user_input"| main
    main -->|"criteria"| tools
    tools -->|"scan_FS"| FS
    tools -->|"read_CSV"| CSV
    tools -->|"parse_input"| Manual
    tools -->|"copy_matches"| Output

    %% Test Dependencies
    test0 --> main
    test1 --> tools
    test2 --> tools

    %% Legacy/Backlog (no runtime flow)
    othersLegacy -.-> othersTodo

    %% Click Events
    click main "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/main.py"
    click msg "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/msg.py"
    click tools "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/tools.py"
    click CSV "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/CallsList.csv"
    click test0 "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/test/test_lvl0.py"
    click test1 "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/test/testlvl1.py"
    click test2 "https://github.com/youssef-rahmouni/vocalrecovery/blob/main/test/testlvl2.py"
    click othersLegacy "https://github.com/youssef-rahmouni/vocalrecovery/tree/main/others/legacys"
    click othersTodo "https://github.com/youssef-rahmouni/vocalrecovery/tree/main/others/ToDo"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#1f78b4,color:#1f78b4,stroke-width:1px
    classDef ui fill:#e0f3ff,stroke:#66a3ff,color:#0059b3,stroke-width:1px
    classDef logic fill:#d4edda,stroke:#28a745,color:#155724,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#ffc107,color:#856404,stroke-width:1px
    classDef sink fill:#ffe5cc,stroke:#ff8c00,color:#994d00,stroke-width:1px
    classDef dev fill:#f0f0f0,stroke:#6c757d,color:#6c757d,stroke-width:1px,stroke-dasharray: 2 2
```
