# soheil7799/mecas-service architecture

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

- Interactive diagram: https://gitdiagram.com/soheil7799/mecas-service
- Repository: https://github.com/soheil7799/mecas-service

## Overview

##### Project Type and Purpose
- MECAS is a full-stack web service designed for uploading, processing (applying audio and video filters), and streaming audio/video files. The project implements audio filtering using custom Python implementations and video filtering using FFmpeg. It provides a REST API using FastAPI to handle file uploads, filter configuration, processing, and real-time streaming.

##### Analyzing the File Structure
- Top-level directories/files such as "api", "filters", and "formatings" indicate a separation of concerns:
- "api": Contains the FastAPI endpoints including routers (e.g., filters, stream, upload) which form the core HTTP server.
- "filters": This directory is divided into "audio" and "video", where you have Python modules implementing various audio filters and a video filter manager that uses FFmpeg.
- "formatings": Contains modules for processing/formatting of audio and video files.
- Other important files include:
- main.py: Likely the entry point which initializes the API server.
- Dockerfiles and docker-compose.yml: Suggest containerization and deployment strategies.
- requirements.txt: Lists the Python dependencies.

##### Diagramming the System Architecture
a. Main Components:
- Client Frontend: The HTML/CSS/JavaScript-based UI from which users interact (upload files, set filters, and stream results).
- API Server (Backend): Built with FastAPI, this server provides endpoints (upload, filter configuration, streaming) and handles the request lifecycle.
- Audio Filter Module: Python implementation modules for processing audio (gain compression, voice enhancement, noise reduction, etc.).
- File Formatting & Management: Modules in the "formatings" directory that prepare or adjust media files as needed before or after filtering.
- External Service / Library: FFmpeg, which is an external dependency especially critical for video filtering.
- Deployment Environment: Dockerized containers (Dockerfiles, docker-compose) representing how the application is packaged and deployed.

b. Relationships and Interactions:
- The Client sends HTTP requests (upload, filter configuration, streaming) to the API Server.
- The API Server, upon receiving a request, dispatches the job to the appropriate router: upload requests go to the upload endpoint, filtering is done via the filters endpoint, and streaming is handled via the stream endpoint.
- When processing is required, the API server invokes the appropriate filter modules:
- For audio: calls functions in the “filters/audio” modules.
- For video: triggers the FFmpeg-based processing via functions in "filters/video/video_filter_manager.py".
- The Formatting modules process media files as necessary, ensuring consistency before and after filtering.
- The API Server then returns processed output back to the client (either file response for download or a stream-generating endpoint for real-time processing).

c. Architectural Patterns and Design Principles:
- Separation of Concerns: Clearly divided modules – API, filters, formatting – each handling a specific processing task.
- Modular Design: Dividing audio and video processing into their respective directories to enable extensibility.
- Microservices-ish Deployment: Even though everything might be running in a single container for the project, Docker and docker-compose configuration hint at containerizing components, which can be later deployed as separate services if needed.
- Integration of External Services: Use of FFmpeg as an external service/library for video filtering.

d. Relevant Technologies & Frameworks:
- FastAPI (Python) for the backend HTTP server.
- Custom Python implementations using SciPy and NumPy for processing audio.
- FFmpeg for video processing.
- Docker (Dockerfiles and docker-compose) for containerization.
- HTML/CSS/JavaScript for the client-side UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level: Client and Main Entry
    Client["Client Frontend"]:::frontend
    MainEntryPoint["Main Entry Point"]:::main

    %% API Server and Routers
    APIServer["API Server (Backend)"]:::backend
    APIRouters["API Routers"]:::router

    RouterFilters["Router: Filters"]:::router
    RouterUpload["Router: Upload"]:::router
    RouterStream["Router: Stream"]:::router

    %% Processing Modules
    AudioFilterModule["Audio Filter Module"]:::processing
    VideoFilterModule["Video Filter Module"]:::processing
    FileFormattingModule["File Formatting & Management"]:::processing

    %% External Service
    FFmpeg["External Service: FFmpeg"]:::external

    %% Deployment Environment
    DeploymentEnvironment["Deployment Environment (Docker)"]:::deployment

    %% Data Flow Connections
    Client -->|"HTTPRequest"| APIServer
    MainEntryPoint -->|"Starts"| APIServer
    APIServer -->|"Dispatches"| APIRouters

    %% Routers handling different functionalities
    APIRouters -->|"filter"| RouterFilters
    APIRouters -->|"upload"| RouterUpload
    APIRouters -->|"stream"| RouterStream

    %% Filter Router to Processing Modules
    RouterFilters -->|"process audio"| AudioFilterModule
    RouterFilters -->|"process video"| VideoFilterModule

    %% Video Filter Module uses External Service
    VideoFilterModule -->|"calls"| FFmpeg

    %% Routers for upload and stream invoke formatting
    RouterUpload -->|"formats"| FileFormattingModule
    RouterStream -->|"formats"| FileFormattingModule

    %% Indicate containerized deployment connections
    APIServer -->|"contained in"| DeploymentEnvironment
    AudioFilterModule -->|"containerized"| DeploymentEnvironment
    VideoFilterModule -->|"containerized"| DeploymentEnvironment
    FileFormattingModule -->|"containerized"| DeploymentEnvironment

    %% Click Events
    click APIServer "https://github.com/soheil7799/mecas-service/blob/main/api/api.py"
    click APIRouters "https://github.com/soheil7799/mecas-service/tree/main/api/routers/"
    click RouterFilters "https://github.com/soheil7799/mecas-service/blob/main/api/routers/filters.py"
    click RouterUpload "https://github.com/soheil7799/mecas-service/blob/main/api/routers/upload.py"
    click RouterStream "https://github.com/soheil7799/mecas-service/blob/main/api/routers/stream.py"
    click AudioFilterModule "https://github.com/soheil7799/mecas-service/tree/main/filters/audio/"
    click VideoFilterModule "https://github.com/soheil7799/mecas-service/blob/main/filters/video/video_filter_manager.py"
    click FileFormattingModule "https://github.com/soheil7799/mecas-service/tree/main/formatings/"
    click DeploymentEnvironment "https://github.com/soheil7799/mecas-service/blob/main/Dockerfiles/backend.Dockerfile"
    click MainEntryPoint "https://github.com/soheil7799/mecas-service/blob/main/main.py"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef main fill:#FAD7A0,stroke:#F5CBA7,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef router fill:#D6EAF8,stroke:#85C1E9,stroke-width:2px;
    classDef processing fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#EC7063,stroke-width:2px;
    classDef deployment fill:#D7BDE2,stroke:#AF7AC5,stroke-width:2px;
```
