# kkogggokk/fancam_inyourarea architecture

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

- Interactive diagram: https://gitdiagram.com/kkogggokk/fancam_inyourarea
- Repository: https://github.com/kkogggokk/fancam_inyourarea

## Overview

##### Project type and purpose
- This is a full-stack AI video-processing pipeline with four major phases: data collection, model training/inference, video cropping, and a FastAPI-based web front-end.
- Purpose: ingest raw concert footage, detect and track individual Blackpink members’ faces via YOLOv5, crop personalized “fancam” videos per member, and serve them through a web UI.

##### Main components
a. Data-Collecting Module
- .py (Selenium + OpenCV): scrapes images & samples frames every 15 frames from input videos.
b. Modeling Module
- modeling/yolov5 (PyTorch-based YOLOv5 code) for training & inference.
- detect.py: runs inference per frame, writes normalized xywh + class to CSV (loc_test.csv).
c. Video-Cropping Module
- Jupyter notebooks in video-crop/:
- blackpick_csv_seperate.ipynb (fills missing coords, smoothing)
- blackpink_videocrop.ipynb (reads CSV, crops frames to fixed WxH, writes per-member MP4s via OpenCV VideoWriter)
d. Web Service Module
- web/app: FastAPI app (main3.py + helpers.py + Markdown pages)
- web/static: CSS, JS (Popcorn.js), images, cropped videos
- web/templates: Jinja2 HTML (base.html, include/sidebar/topnav, page.html)
- web/requirements.txt lists dependencies
e. Infrastructure & Deployment
- Docker (Dockerfile not shown but implied)
- AWS (EC2 hosting), Nginx (reverse proxy), H.264 video transcoding codec

##### Relationships and data flow
- Raw video files → Data-Collecting Module → sampled frame images → labeling (manual) → Training in Modeling Module → trained YOLOv5 model
- New input videos + trained model → detect.py → per-frame CSV of face coordinates → video-crop notebooks → cropped member videos
- Cropped videos + FastAPI back-end → served to user’s browser (UI syncs multiple video players via Popcorn.js)
- All services containerized and deployed behind Nginx on AWS

##### Architectural patterns & design principles
- Modular batch pipeline: each phase (collect → train → infer → crop) is a standalone component with clear I/O (files, CSVs).
- Microservice-like separation: the web front-end is distinct from heavy compute modules.
- Separation of concerns: static assets vs. dynamic API vs. compute jobs.

##### Relevant technologies & frameworks
- Python ecosystem: OpenCV, Pandas, NumPy for data prep; PyTorch YOLOv5 for detection; FastAPI for REST/web layers.
- Front-end: HTML templates (Jinja2), CSS, JS (Popcorn.js for video sync).
- Deployment: Docker containers, AWS EC2, Nginx proxy, H.264 video codec for browser compatibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Pipeline Layer
    subgraph "Data Pipeline"
        direction TB
        RawVideos["Raw Video Files (.mp4)"]:::storage
        capture["capture.py<br/>(Selenium + OpenCV)"]:::batch
        label["LabelImg<br/>(Manual Annotation)"]:::external
        frames["Sampled Frames (.jpg)"]:::storage
        yolov5["YOLOv5 Code"]:::batch
        detect["detect.py<br/>(Inference)"]:::batch
        loccsv["loc_test.csv"]:::storage
        sep["blackpick_csv_seperate.ipynb"]:::batch
        cropnb["blackpink_videocrop.ipynb"]:::batch
        cropped["Cropped Videos (.mp4)"]:::storage

        RawVideos -->|"input .mp4"| capture
        capture -->|"sample every 15 frames"| frames
        frames -->|"annotate bounding boxes"| label
        label -->|"training data"| yolov5
        yolov5 -->|"runs inference"| detect
        detect -->|"outputs .csv coords"| loccsv
        loccsv -->|"fills & smooths coords"| sep
        sep -->|"reads CSV"| cropnb
        cropnb -->|"writes per-member .mp4"| cropped
    end

    %% Web Layer
    subgraph "Web Layer"
        direction TB
        api["main3.py<br/>(FastAPI)"]:::api
        helpers["helpers.py"]:::api
        mdHome["home.md"]:::api
        mdProfile["profile.md"]:::api
        templates["Jinja2 Templates"]:::api
        staticcss["CSS Files"]:::api
        staticjs["Popcorn.js"]:::api
        staticvids["Cropped Videos"]:::storage
        requirements["requirements.txt"]:::api
        browser["User Browser"]:::external

        api --> helpers
        api --> mdHome
        api --> mdProfile
        api --> templates
        api --> staticcss
        api --> staticjs
        api --> staticvids
        api --> requirements
        browser -->|"HTTP/JSON & video requests"| api
        staticvids --> browser
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        docker["Docker Containers"]:::external
        aws["AWS EC2"]:::external
        nginx["Nginx Reverse Proxy"]:::external

        docker --> aws
        aws --> nginx
        nginx --> browser
    end

    %% Integrate Layers
    cropped --> staticvids
    docker --> Data_Pipeline
    docker --> Web_Layer

    %% Click Events
    click capture "https://github.com/kkogggokk/fancam_inyourarea/blob/main/data-collecting/capture.py"
    click yolov5 "https://github.com/kkogggokk/fancam_inyourarea/tree/main/modeling/yolov5/"
    click detect "https://github.com/kkogggokk/fancam_inyourarea/blob/main/modeling/detect.py"
    click sep "https://github.com/kkogggokk/fancam_inyourarea/blob/main/video-crop/blackpick_csv_seperate.ipynb"
    click cropnb "https://github.com/kkogggokk/fancam_inyourarea/blob/main/video-crop/blackpink_videocrop.ipynb"
    click api "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/app/main3.py"
    click helpers "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/app/library/helpers.py"
    click mdHome "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/app/pages/home.md"
    click mdProfile "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/app/pages/profile.md"
    click css1 "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/css/home.css"
    click css2 "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/css/profile.css"
    click css3 "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/css/style3.css"
    click staticjs "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/js/Popcorn.js"
    click jennie "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/videos/jennie.mp4"
    click jisoo "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/videos/jisoo.mp4"
    click lisa "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/videos/lisa.mp4"
    click rose "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/videos/rose.mp4"
    click lovesick "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/videos/bp_lovesickgirl.mp4"
    click ad "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/static/videos/ad.mp4"
    click base "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/templates/base.html"
    click pageT "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/templates/page.html"
    click sidebar "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/templates/include/sidebar.html"
    click topnav "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/templates/include/topnav.html"
    click requirements "https://github.com/kkogggokk/fancam_inyourarea/blob/main/web/requirements.txt"

    %% Styles
    classDef batch fill:#D0E8FF,stroke:#0074D9,color:#000
    classDef api fill:#DFFFD6,stroke:#2ECC40,color:#000
    classDef storage fill:#FFF4D6,stroke:#FF851B,color:#000
    classDef external fill:#EEEEEE,stroke:#AAAAAA,color:#444
    class Data_Pipeline,Web_Layer,Infrastructure external
    class RawVideos,frames,loccsv,staticvids storage
    class capture,yolov5,detect,sep,cropnb batch
    class api,helpers,mdHome,mdProfile,templates,staticcss,staticjs,requirements api
    class docker,aws,nginx external
```
