# yzy-stack/df40 architecture

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

- Interactive diagram: https://gitdiagram.com/yzy-stack/df40
- Repository: https://github.com/yzy-stack/df40

## Overview

##### Main components
a. Data Ingestion & Annotation
- Raw video sources: FaceForensics++ (FF++), Celeb-DF (CDF), other unknown methods
- Annotation archives: A-Celeb-DF.zip, A-FF++.zip
b. Preprocessing Layer
- Scripts: preprocess.py (frame extraction, face crop, landmarks, masks)
- Tools: dlib_tools, shape_predictor_81_face_landmarks.dat
- Configuration: preprocessing/config.yaml
c. Data Rearrangement
- Script: rearrange.py
- Output: JSON files under preprocessing/dataset_json
d. Benchmark & Training Framework (DeepfakeBench_DF40)
- Dataset loaders: training/dataset (abstract_dataset.py, pair_dataset.py, utilities)
- Detectors: training/detectors (xception, clip, i3d, etc.)
- Model definitions: training/networks (ResNet, Xception, HRNet, TimeTransformer, etc.)
- Loss & metrics: training/loss, training/metrics
- Optimizers & schedulers: training/optimizor
- Trainer orchestrator: training/trainer (base_trainer.py, trainer.py), train.py
- Configuration: training/config/{backbone, detector, train_config.yaml, test_config.yaml}
- Shell helpers: run_df40.sh, run_df40.sh variants
e. Inference & Evaluation
- Script: training/test.py
- Inputs: chosen detector YAML + checkpoint (.pth) + target dataset
- Outputs: performance metrics, confidence distributions
f. EFS Fine-tuning Pipeline (EFS_finetune_code)
- Submodule: diffusion_based (LoRA scripts, train_ddpm.py, test_ddim.py, bash scripts)
- Pretrained weights: pytorch_lora_weights.safetensors

##### Relationships & data flow
- Preprocessing outputs (frames, landmarks) → Rearrangement → JSON dataset
- JSON dataset → Dataset loaders → Training
- Training configuration (YAML) → Detector & Model components → Trainer
- Trainer → Checkpoints + Logs
- Checkpoints + JSON dataset → Inference → Metrics

##### Architectural patterns
- Modular ML pipeline: clear separation between data, preprocessing, training, inference
- Configuration-driven: YAML files govern backbone & detector selection, hyperparameters
- Plug-and-play detectors: base_detector + specific detector subclasses
- Extensible dataset utilities: abstract_dataset with pluggable transforms, augmentation

##### Be detailed but focused
- Every top-level directory (Annotations_for_Facial_Attributes, DeepfakeBench_DF40, EFS_finetune_code)
- Inside DeepfakeBench_DF40, break out “preprocessing”, “training”, “dataset”, “detectors”, “networks”, “loss”, “metrics”
- For EFS_finetune_code, show the LoRA training & test scripts as a separate mini-pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Annotation Layer
    subgraph "Data & Annotation"
        AFA["Annotations_for_Facial_Attributes"]:::data
        AZip1["A-Celeb-DF.zip"]:::data
        AZip2["A-FF++.zip"]:::data
        RawFF["FaceForensics++"]:::external
        RawCDF["Celeb-DF"]:::external
        AFA --> AZip1
        AFA --> AZip2
    end

    %% Preprocessing & Rearrangement Layer
    subgraph "Preprocessing & Rearrangement"
        Preproc["preprocess.py"]:::code
        ConfigPre["config.yaml"]:::code
        DlibTool["shape_predictor_81_face_landmarks.dat"]:::external
        DlibReadme["readme.md"]:::external
        Rearr["rearrange.py"]:::code
        JSONStore["dataset_json/"]:::data
        DownloadTxt["download_JSON.txt"]:::data

        Preproc --> ConfigPre
        Preproc --> DlibTool
        Preproc --> DlibReadme
        Preproc --> Rearr
        Rearr --> JSONStore
        JSONStore --> DownloadTxt
    end

    %% Model Training & Inference Layer
    subgraph "Model Training & Inference"
        subgraph "Dataset Loader"
            AbsDS["abstract_dataset.py"]:::code
            PairDS["pair_dataset.py"]:::code
            Albu["albu.py"]:::code
            DSUtils["utils/"]:::code
        end

        subgraph "Detectors"
            BaseDet["base_detector.py"]:::code
            ClipDet["clip_detector.py"]:::code
            I3DDet["i3d_detector.py"]:::code
            RecceDet["recce_detector.py"]:::code
            RFMDet["rfm_detector.py"]:::code
            SBIDet["sbi_detector.py"]:::code
            SPSLDet["spsl_detector.py"]:::code
            SRMDet["srm_detector.py"]:::code
            XcepDet["xception_detector.py"]:::code
            DetUtils["utils/"]:::code
        end

        subgraph "Networks"
            ResNet["resnet.py"]:::code
            XcepNet["xception.py"]:::code
            HRNet["cls_hrnet.py"]:::code
            TimeTrans["time_transformer.py"]:::code
        end

        subgraph "Loss & Metrics"
            LossCode["loss/"]:::code
            Metrics["metrics/"]:::code
        end

        subgraph "Optimizer"
            OptLin["LinearLR.py"]:::code
            OptSAM["SAM.py"]:::code
        end

        subgraph "Trainer Orchestrator"
            BaseTr["base_trainer.py"]:::code
            TrScript["trainer.py"]:::code
            TrainEntry["train.py"]:::code
            TestEntry["test.py"]:::code
            RunSh["run_df40.sh"]:::code
            LogDraw["logits_confidence_dist_draw.py"]:::code
            Checkpoint["Checkpoints/.pth"]:::data
        end

        subgraph "Configuration"
            TrainConf["train_config.yaml"]:::code
            TestConf["test_config.yaml"]:::code
            BackboneConf["cls_hrnet_w48.yaml"]:::code
            DetConf["detector/*.yaml"]:::code
        end

        %% Data & Config flows
        JSONStore --> AbsDS
        JSONStore --> LoRATrain
        TrainConf --> BaseTr
        TestConf --> TestEntry
        BackboneConf --> ResNet
        BackboneConf --> XcepNet
        BackboneConf --> HRNet
        BackboneConf --> TimeTrans
        DetConf --> ClipDet
        DetConf --> I3DDet
        DetConf --> RecceDet
        DetConf --> RFMDet
        DetConf --> SBIDet
        DetConf --> SPSLDet
        DetConf --> SRMDet
        DetConf --> XcepDet

        %% Module connections
        AbsDS --> BaseTr
        PairDS --> BaseTr
        BaseDet --> BaseTr
        ClipDet --> BaseTr
        I3DDet --> BaseTr
        ResNet --> BaseTr
        XcepNet --> BaseTr
        HRNet --> BaseTr
        TimeTrans --> BaseTr
        LossCode --> BaseTr
        Metrics --> BaseTr
        OptLin --> BaseTr
        OptSAM --> BaseTr

        %% Training & Inference
        TrainEntry --> BaseTr
        BaseTr --> Checkpoint
        Checkpoint --> TestEntry
        TestEntry --> Metrics
    end

    %% EFS Fine-tuning Pipeline
    subgraph "EFS Fine-tuning Pipeline"
        subgraph "Diffusion Based"
            LoRATrain["train_ddpm.py"]:::code
            LoRAScripts["*.py"]:::code
            LoRATest["*.py"]:::code
            BashScripts["*.sh"]:::code
            Weights["pytorch_lora_weights.safetensors"]:::data
        end
        JSONStore --> LoRATrain
    end

    %% Links between layers
    AZip1 --> Preproc
    AZip2 --> Preproc
    RawFF --> Preproc
    RawCDF --> Preproc

    %% Click Events
    click AFA "https://github.com/yzy-stack/df40/tree/main/Annotations_for_Facial_Attributes/"
    click AZip1 "https://github.com/yzy-stack/df40/blob/main/Annotations_for_Facial_Attributes/A-Celeb-DF.zip"
    click AZip2 "https://github.com/yzy-stack/df40/blob/main/Annotations_for_Facial_Attributes/A-FF++.zip"
    click Preproc "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/preprocessing/preprocess.py"
    click ConfigPre "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/preprocessing/config.yaml"
    click DlibTool "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/preprocessing/dlib_tools/shape_predictor_81_face_landmarks.dat"
    click DlibReadme "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/preprocessing/dlib_tools/readme.md"
    click Rearr "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/preprocessing/rearrange.py"
    click JSONStore "https://github.com/yzy-stack/df40/tree/main/DeepfakeBench_DF40/preprocessing/dataset_json/"
    click DownloadTxt "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/preprocessing/dataset_json/download_JSON.txt"
    click AbsDS "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/dataset/abstract_dataset.py"
    click PairDS "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/dataset/pair_dataset.py"
    click Albu "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/dataset/albu.py"
    click DSUtils "https://github.com/yzy-stack/df40/tree/main/DeepfakeBench_DF40/training/dataset/utils/"
    click BaseDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/base_detector.py"
    click ClipDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/clip_detector.py"
    click I3DDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/i3d_detector.py"
    click RecceDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/recce_detector.py"
    click RFMDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/rfm_detector.py"
    click SBIDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/sbi_detector.py"
    click SPSLDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/spsl_detector.py"
    click SRMDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/srm_detector.py"
    click XcepDet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/detectors/xception_detector.py"
    click ResNet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/networks/resnet.py"
    click XcepNet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/networks/xception.py"
    click HRNet "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/networks/cls_hrnet.py"
    click TimeTrans "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/networks/time_transformer.py"
    click OptLin "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/optimizor/LinearLR.py"
    click OptSAM "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/optimizor/SAM.py"
    click BaseTr "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/trainer/base_trainer.py"
    click TrScript "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/trainer/trainer.py"
    click TrainEntry "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/train.py"
    click TestEntry "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/test.py"
    click RunSh "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/run_df40.sh"
    click TrainConf "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/config/train_config.yaml"
    click TestConf "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/config/test_config.yaml"
    click BackboneConf "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/config/backbone/cls_hrnet_w48.yaml"
    click DetConf "https://github.com/yzy-stack/df40/blob/main/DeepfakeBench_DF40/training/config/detector/*.yaml"
    click LoRATrain "https://github.com/yzy-stack/df40/blob/main/EFS_finetune_code/diffusion_based/train_scripts/train_ddpm.py"
    click LoRAScripts "https://github.com/yzy-stack/df40/tree/main/EFS_finetune_code/diffusion_based/train_scripts/"
    click LoRATest "https://github.com/yzy-stack/df40/tree/main/EFS_finetune_code/diffusion_based/test_scripts/"
    click BashScripts "https://github.com/yzy-stack/df40/tree/main/EFS_finetune_code/diffusion_based/bash_scripts/"
    click Weights "https://github.com/yzy-stack/df40/blob/main/EFS_finetune_code/diffusion_based/pytorch_lora_weights.safetensors"

    %% Styles
    classDef data fill:#a6cee3,stroke:#333,stroke-width:1px
    classDef code fill:#b2df8a,stroke:#333,stroke-width:1px
    classDef external fill:#fdbf6f,stroke:#333,stroke-width:1px
```
