# roshanbvadassery/bairaneffect architecture

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

- Interactive diagram: https://gitdiagram.com/roshanbvadassery/bairaneffect
- Repository: https://github.com/roshanbvadassery/bairaneffect

## Overview

1. This repository is a small Node.js video-processing pipeline with two entry points: a command-line script flow and an HTTP API server. The core job is to transform a source video into a final composed output with a freeze-frame transition, background removal, optional slideshow, and final compositing.

2. The pipeline is split into four explicit stages, each represented by a top-level script:
   - `step1-extract-last-frame.js` reads the source video and extracts the final frame.
   - `step2-remove-background.js` processes that frame to remove the background using an AI-backed step.
   - `step3-add-borders.js` turns the cutout into a sticker-like asset by adding borders.
   - `step4-compose-video.js` assembles the final video from the processed frame plus a middle segment.

3. The data flow is file-based and sequential. Intermediate artifacts are written into `output/` and reused by later stages. The main outputs named in the README are:
   - `output/last-frame.png`
   - `output/bg-removed.png`
   - `output/bordered-image.png`
   - `output/final-video.mp4`
   This makes the pipeline easy to diagram as a linear chain of generated files.

4. The input side is flexible. The system can accept:
   - a local video file path
   - a remote video URL
   - an optional local ZIP of images
   - an optional remote ZIP URL
   The API server is the boundary that normalizes these inputs before handing them to the processing steps.

5. `server.js` is the orchestration layer. It exposes:
   - `POST /process` to start the workflow
   - `GET /download/:filename` to fetch generated outputs
   - `GET /status` for health/status checks
   So the server is not doing heavy media work itself; it coordinates the pipeline and serves generated artifacts.

6. There is a second media branch for the “middle” portion of the final video. `create-middle-slideshow.js` can generate `output/middle-slideshow.mp4` from images in `middle-images/`. If that slideshow exists, step 4 uses it; otherwise it falls back to `middle-video.mp4`. That is an important conditional boundary in the architecture.

7. The repo depends on native media tooling rather than pure JavaScript processing. The README indicates:
   - `ffmpeg` / `ffprobe` for video inspection and compositing
   - `sips` on macOS for image conversion
   This means the runtime is Node.js plus external binaries, so the architecture has a strong OS/tooling dependency layer.

8. The processing model is artifact-driven and local-filesystem-centric. Inputs, intermediates, and final outputs are all stored on disk under repository folders such as `middle-images/` and `output/`. That suggests the system is optimized for batch processing and file handoff between steps, not for in-memory streaming.

9. Packaging and deployment are supported through containerization. The presence of `Dockerfile`, `docker-compose.yml`, and `.dockerignore` indicates the pipeline can be run in a controlled environment where FFmpeg and Node dependencies are bundled. This matters because the architecture relies on external binaries and macOS-specific behavior in at least one path.

10. In diagram terms, the main boundaries are:
   - client/API boundary into `server.js`
   - input normalization boundary for local files vs URLs
   - step-by-step media transformation boundary across `step1`–`step4`
   - optional slideshow branch feeding step 4
   - filesystem artifact boundary for `output/`
   - external tooling boundary for FFmpeg and image utilities
   The overall architecture is best understood as a deterministic media pipeline orchestrated by Node.js.

Main entry points: [`step4-compose-video.js`](https://github.com/roshanbvadassery/bairaneffect/blob/master/step4-compose-video.js) (Compose video), [`server.js`](https://github.com/roshanbvadassery/bairaneffect/blob/master/server.js) (server.js), [`step1-extract-last-frame.js`](https://github.com/roshanbvadassery/bairaneffect/blob/master/step1-extract-last-frame.js) (Extract frame), [`step2-remove-background.js`](https://github.com/roshanbvadassery/bairaneffect/blob/master/step2-remove-background.js) (Remove bg)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_client(("Client<br/>requester"))
  node_server["server.js<br/>api/orchestrator<br/>[server.js]"]
  node_inputs["Input normalizer<br/>boundary"]
  node_local_video["Local video<br/>input"]
  node_remote_video["Remote video<br/>input"]
  node_local_zip["Image ZIP<br/>input"]
  node_remote_zip["ZIP URL<br/>input"]
end

subgraph group_pipeline["Media Pipeline"]
  node_step1["Extract frame<br/>frame extract"]
  node_step2["Remove bg<br/>bg removal"]
  node_step3["Add borders<br/>image polish"]
  node_slideshow["Middle slideshow<br/>optional branch"]
  node_step4["Compose video<br/>final compose"]
  node_last_frame["last-frame.png<br/>artifact"]
  node_bg_removed["bg-removed.png<br/>artifact"]
  node_bordered["bordered-image.png<br/>artifact"]
  node_middle_show["middle-slideshow.mp4<br/>artifact"]
  node_final_video["final-video.mp4<br/>artifact"]
end

subgraph group_tools["External Tools"]
  node_ffmpeg{{"FFmpeg<br/>media binary"}}
  node_sips{{"sips<br/>image utility"}}
end

subgraph group_runtime["Runtime"]
  node_docker["Docker<br/>packaging"]
end

node_client -->|"POST /process"| node_server
node_server -->|"normalize"| node_inputs
node_server -.->|"deploy"| node_docker
node_local_video -->|"source video"| node_inputs
node_remote_video -->|"source video"| node_inputs
node_local_zip -->|"optional images"| node_inputs
node_remote_zip -->|"optional images"| node_inputs
node_inputs -->|"video path"| node_step1
node_step1 -->|"write"| node_last_frame
node_last_frame -->|"frame input"| node_step2
node_step2 -->|"write"| node_bg_removed
node_bg_removed -->|"cutout input"| node_step3
node_step3 -->|"write"| node_bordered
node_inputs -->|"optional images"| node_slideshow
node_slideshow -->|"write"| node_middle_show
node_bordered -->|"visual overlay"| node_step4
node_middle_show -->|"preferred middle"| node_step4
node_step4 -->|"write"| node_final_video
node_step1 -->|"inspect"| node_ffmpeg
node_step2 -->|"process"| node_ffmpeg
node_step3 -->|"convert"| node_sips
node_step4 -->|"compose"| node_ffmpeg

click node_server "https://github.com/roshanbvadassery/bairaneffect/blob/master/server.js"
click node_step1 "https://github.com/roshanbvadassery/bairaneffect/blob/master/step1-extract-last-frame.js"
click node_step2 "https://github.com/roshanbvadassery/bairaneffect/blob/master/step2-remove-background.js"
click node_step3 "https://github.com/roshanbvadassery/bairaneffect/blob/master/step3-add-borders.js"
click node_slideshow "https://github.com/roshanbvadassery/bairaneffect/blob/master/create-middle-slideshow.js"
click node_step4 "https://github.com/roshanbvadassery/bairaneffect/blob/master/step4-compose-video.js"
click node_docker "https://github.com/roshanbvadassery/bairaneffect/tree/master/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_inputs,node_local_video,node_remote_video,node_local_zip,node_remote_zip toneBlue
class node_step1,node_step2,node_step3,node_slideshow,node_step4,node_last_frame,node_bg_removed,node_bordered,node_middle_show,node_final_video toneAmber
class node_ffmpeg,node_sips toneMint
class node_docker toneRose
```

## Components

### Orchestration

HTTP boundary and input normalization

- **Client**: requester · Starts processing through the API
- [server.js](https://github.com/roshanbvadassery/bairaneffect/blob/master/server.js): api/orchestrator · HTTP API and workflow coordination · `server.js`
- **Input normalizer**: boundary · Normalizes local files and remote URLs before processing
- **Local video**: input · Local source video path
- **Remote video**: input · Video fetched from a URL
- **Image ZIP**: input · Optional local ZIP of images
- **ZIP URL**: input · Optional remote ZIP of images

### Media Pipeline

Sequential artifact-driven processing stages

- [Extract frame](https://github.com/roshanbvadassery/bairaneffect/blob/master/step1-extract-last-frame.js): frame extract · Reads the source video and extracts the last frame · `step1-extract-last-frame.js`
- [Remove bg](https://github.com/roshanbvadassery/bairaneffect/blob/master/step2-remove-background.js): bg removal · AI-backed background removal for the extracted frame · `step2-remove-background.js`
- [Add borders](https://github.com/roshanbvadassery/bairaneffect/blob/master/step3-add-borders.js): image polish · Turns the cutout into a sticker-like bordered asset · `step3-add-borders.js`
- [Middle slideshow](https://github.com/roshanbvadassery/bairaneffect/blob/master/create-middle-slideshow.js): optional branch · Builds a slideshow video from middle-images when present · `create-middle-slideshow.js`
- [Compose video](https://github.com/roshanbvadassery/bairaneffect/blob/master/step4-compose-video.js): final compose · Assembles the final output video from processed assets and middle segment · `step4-compose-video.js`
- **last-frame.png**: artifact · Extracted final frame written under output/
- **bg-removed.png**: artifact · Background-removed cutout written under output/
- **bordered-image.png**: artifact · Bordered image written under output/
- **middle-slideshow.mp4**: artifact · Optional middle segment written under output/
- **final-video.mp4**: artifact · Final composed video written under output/

### External Tools

Native binaries and OS utilities used by the pipeline

- **FFmpeg**: media binary · Video inspection, transcoding, and compositing
- **sips**: image utility · macOS image conversion helper

### Runtime

Packaging and execution environment

- [Docker](https://github.com/roshanbvadassery/bairaneffect/tree/master/Dockerfile): packaging · Containerized runtime and dependency bundling · `Dockerfile`

## Connections

- Client → server.js: POST /process · Starts a processing run
- server.js → Input normalizer: normalize · Prepares source and optional image inputs
- server.js → Docker: deploy · Runs in a containerized environment when packaged
- Local video → Input normalizer: source video · Local file input
- Remote video → Input normalizer: source video · Remote URL input
- Image ZIP → Input normalizer: optional images · Optional local image bundle
- ZIP URL → Input normalizer: optional images · Optional remote image bundle
- Input normalizer → Extract frame: video path · Hands off normalized source media
- Extract frame → last-frame.png: write · Extracted final frame artifact
- last-frame.png → Remove bg: frame input · Feeds background removal
- Remove bg → bg-removed.png: write · Background-removed artifact
- bg-removed.png → Add borders: cutout input · Feeds border/sticker pass
- Add borders → bordered-image.png: write · Bordered image artifact
- Input normalizer → Middle slideshow: optional images · Uses middle-images when present
- Middle slideshow → middle-slideshow.mp4: write · Optional middle slideshow artifact
- bordered-image.png → Compose video: visual overlay · Final compositing input
- middle-slideshow.mp4 → Compose video: preferred middle · Used when the slideshow exists
- Compose video → final-video.mp4: write · Final video artifact
- Extract frame → FFmpeg: inspect · Video frame extraction depends on FFmpeg
- Remove bg → FFmpeg: process · Media processing relies on FFmpeg tooling
- Add borders → sips: convert · Border generation uses macOS image utilities
- Compose video → FFmpeg: compose · Final assembly uses FFmpeg
