# krishank-kureti/framekraft architecture

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

- Interactive diagram: https://gitdiagram.com/krishank-kureti/framekraft
- Repository: https://github.com/krishank-kureti/framekraft

## Overview

FrameKraft turns an uploaded image and user-supplied mood and editing vibe into ranked image captions, mood-stylized caption options, an edited image, and matching song previews. The documented web flow enters through FastAPI; its pipeline orchestrator invokes captioning, classification, stylization, editing, and music recommendation stages. The CLI is a separate entry point with a similar workflow. README describes the frontend experience, while the tree contains only frontend/index.html; unsampled frontend behavior and some backend modules are represented only where documentation supports them.

Main entry points: [`backend/app/core/pipeline.py`](https://github.com/krishank-kureti/framekraft/blob/main/backend/app/core/pipeline.py) (Image pipeline), [`backend/Start.py`](https://github.com/krishank-kureti/framekraft/blob/main/backend/Start.py) (Interactive CLI), [`backend/MusicRag.py`](https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicRag.py) (Music RAG), [`frontend/index.html`](https://github.com/krishank-kureti/framekraft/blob/main/frontend/index.html) (FrameKraft UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["FrameKraft UI<br/>[index.html]"]
  node_api["FastAPI service<br/>[main.py]"]
  node_upload["Pipeline endpoint<br/>[pipeline.py]"]
  node_orchestrator["Image pipeline<br/>[pipeline.py]"]
  node_image_helpers["Image utilities<br/>[image.py]"]
end

subgraph group_visual["Image understanding and editing"]
  node_blip["BLIP captioning<br/>[Blip.py]"]
  node_clip["CLIP ranking<br/>[Clip.py]"]
  node_stylize["Caption stylization<br/>[Start.py]"]
  node_edit_commands["Edit command generation<br/>[CvEdit.py]"]
  node_image_editor["OpenCV editor<br/>[CvEdit.py]"]
end

subgraph group_music["Music recommendations"]
  node_music_recommender["Music RAG<br/>[MusicRag.py]"]
  node_song_store[("Song index")]
  node_encoder["Song database encoder<br/>[MusicEncoder.py]"]
  node_preview_lookup["Preview lookup<br/>[MusicSources.py]"]
end

subgraph group_cli["CLI workflow"]
  node_cli["Interactive CLI<br/>[Start.py]"]
end

node_visitor(("Image user"))
node_groq{{"Groq API"}}
node_itunes{{"iTunes previews"}}

node_visitor -->|"uses"| node_webapp
node_webapp -->|"requests page"| node_api
node_webapp -->|"uploads image"| node_upload
node_api -->|"registers route"| node_upload
node_upload -->|"invokes pipeline"| node_orchestrator
node_orchestrator -->|"generates captions"| node_blip
node_orchestrator -->|"ranks captions"| node_clip
node_orchestrator -->|"styles caption"| node_stylize
node_orchestrator -->|"requests edits"| node_edit_commands
node_orchestrator -->|"applies edits"| node_image_editor
node_orchestrator -->|"requests songs"| node_music_recommender
node_stylize -->|"calls model"| node_groq
node_edit_commands -->|"calls model"| node_groq
node_music_recommender -->|"extracts tags"| node_groq
node_music_recommender -->|"queries index"| node_song_store
node_music_recommender -->|"looks up previews"| node_preview_lookup
node_preview_lookup -.->|"fetches previews"| node_itunes
node_encoder -->|"writes embeddings"| node_song_store
node_cli -->|"generates captions"| node_blip
node_cli -->|"ranks captions"| node_clip
node_cli -->|"styles caption"| node_stylize
node_cli -->|"edits image"| node_image_editor
node_cli -->|"requests songs"| node_music_recommender

click node_webapp "https://github.com/krishank-kureti/framekraft/blob/main/frontend/index.html"
click node_api "https://github.com/krishank-kureti/framekraft/blob/main/backend/app/main.py"
click node_upload "https://github.com/krishank-kureti/framekraft/blob/main/backend/app/api/pipeline.py"
click node_orchestrator "https://github.com/krishank-kureti/framekraft/blob/main/backend/app/core/pipeline.py"
click node_image_helpers "https://github.com/krishank-kureti/framekraft/blob/main/backend/app/utils/image.py"
click node_blip "https://github.com/krishank-kureti/framekraft/blob/main/backend/Blip.py"
click node_clip "https://github.com/krishank-kureti/framekraft/blob/main/backend/Clip.py"
click node_stylize "https://github.com/krishank-kureti/framekraft/blob/main/backend/Start.py"
click node_edit_commands "https://github.com/krishank-kureti/framekraft/blob/main/backend/CvEdit.py"
click node_image_editor "https://github.com/krishank-kureti/framekraft/blob/main/backend/CvEdit.py"
click node_music_recommender "https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicRag.py"
click node_song_store "https://github.com/krishank-kureti/framekraft/tree/main/backend/data/chroma_db"
click node_encoder "https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicEncoder.py"
click node_preview_lookup "https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicSources.py"
click node_cli "https://github.com/krishank-kureti/framekraft/blob/main/backend/Start.py"

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_webapp,node_api,node_upload,node_orchestrator,node_image_helpers,node_visitor,node_itunes toneBlue
class node_blip,node_clip,node_stylize,node_edit_commands,node_image_editor toneAmber
class node_music_recommender,node_song_store,node_encoder,node_preview_lookup,node_groq toneMint
class node_cli toneRose
```

## Components

### Web application

- [FrameKraft UI](https://github.com/krishank-kureti/framekraft/blob/main/frontend/index.html): `frontend/index.html`
- [FastAPI service](https://github.com/krishank-kureti/framekraft/blob/main/backend/app/main.py): `backend/app/main.py`
- [Pipeline endpoint](https://github.com/krishank-kureti/framekraft/blob/main/backend/app/api/pipeline.py): `backend/app/api/pipeline.py`
- [Image pipeline](https://github.com/krishank-kureti/framekraft/blob/main/backend/app/core/pipeline.py): `backend/app/core/pipeline.py`
- [Image utilities](https://github.com/krishank-kureti/framekraft/blob/main/backend/app/utils/image.py): `backend/app/utils/image.py`

### Image understanding and editing

- [BLIP captioning](https://github.com/krishank-kureti/framekraft/blob/main/backend/Blip.py): `backend/Blip.py`
- [CLIP ranking](https://github.com/krishank-kureti/framekraft/blob/main/backend/Clip.py): `backend/Clip.py`
- [Caption stylization](https://github.com/krishank-kureti/framekraft/blob/main/backend/Start.py): `backend/Start.py`
- [Edit command generation](https://github.com/krishank-kureti/framekraft/blob/main/backend/CvEdit.py): `backend/CvEdit.py`
- [OpenCV editor](https://github.com/krishank-kureti/framekraft/blob/main/backend/CvEdit.py): `backend/CvEdit.py`

### Music recommendations

- [Music RAG](https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicRag.py): `backend/MusicRag.py`
- [Song index](https://github.com/krishank-kureti/framekraft/tree/main/backend/data/chroma_db): `backend/data/chroma_db`
- [Song database encoder](https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicEncoder.py): `backend/MusicEncoder.py`
- [Preview lookup](https://github.com/krishank-kureti/framekraft/blob/main/backend/MusicSources.py): `backend/MusicSources.py`

### CLI workflow

- [Interactive CLI](https://github.com/krishank-kureti/framekraft/blob/main/backend/Start.py): `backend/Start.py`

### Other components

- **Image user**
- **Groq API**
- **iTunes previews**

## Connections

- Image user → FrameKraft UI: uses
- FrameKraft UI → FastAPI service: requests page
- FrameKraft UI → Pipeline endpoint: uploads image
- FastAPI service → Pipeline endpoint: registers route
- Pipeline endpoint → Image pipeline: invokes pipeline
- Image pipeline → BLIP captioning: generates captions
- Image pipeline → CLIP ranking: ranks captions
- Image pipeline → Caption stylization: styles caption
- Image pipeline → Edit command generation: requests edits
- Image pipeline → OpenCV editor: applies edits
- Image pipeline → Music RAG: requests songs
- Caption stylization → Groq API: calls model
- Edit command generation → Groq API: calls model
- Music RAG → Groq API: extracts tags
- Music RAG → Song index: queries index
- Music RAG → Preview lookup: looks up previews
- Preview lookup → iTunes previews: fetches previews
- Song database encoder → Song index: writes embeddings
- Interactive CLI → BLIP captioning: generates captions
- Interactive CLI → CLIP ranking: ranks captions
- Interactive CLI → Caption stylization: styles caption
- Interactive CLI → OpenCV editor: edits image
- Interactive CLI → Music RAG: requests songs