# teampixai/teampixpython architecture

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

- Interactive diagram: https://gitdiagram.com/teampixai/teampixpython
- Repository: https://github.com/teampixai/teampixpython

## Overview

TeamPixPython is a local sports-photo culling application: users configure a team and album in the browser, import photos for analysis, review sharpness and other-team filtering, optionally identify players or use AI features, then export keepers. The graph preserves the documented face, jersey, burst-ranking, editing, and export capabilities. Some UI and subsystem sources were not sampled; edges for those features are limited to README descriptions or omitted where wiring is not evidenced.

Main entry points: [`1_prep_review.py`](https://github.com/teampixai/teampixpython/blob/main/1_prep_review.py) (Photo import), [`culling_app.py`](https://github.com/teampixai/teampixpython/blob/main/culling_app.py) (Local web app), [`algo/stages/image_analysis.py`](https://github.com/teampixai/teampixpython/blob/main/algo/stages/image_analysis.py) (Image and pose analysis), [`webui/culling/static/js/album-tools.js`](https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/album-tools.js) (Album tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application workflow"]
  node_webapp["Local web app<br/>[culling_app.py]"]
  node_import["Photo import<br/>[1_prep_review.py]"]
  node_team["Team setup<br/>[team.js]"]
  node_albumselect["Album selection<br/>[select-album.js]"]
end

subgraph group_analysis["Photo analysis"]
  node_config["Analysis settings<br/>[config.py]"]
  node_imageanalysis["Image and pose analysis<br/>[image_analysis.py]"]
  node_detectors["MediaPipe detection"]
  node_grading["Face sharpness grading<br/>[grading.py]"]
  node_jersey["Jersey filtering<br/>[jersey_counting.py]"]
  node_annotations["Photo annotations<br/>[annotation.py]"]
  node_frames["Frame data<br/>[frame.py]"]
end

subgraph group_identity["Faces and players"]
  node_facerec["Face recognition<br/>[facereco.py]"]
  node_facecrop["Face crops and embeddings<br/>[face_crop_embed.py]"]
  node_faceui["Face management<br/>[faces.js]"]
end

subgraph group_review["Review and editing"]
  node_llmstage["Burst ranking and ratings<br/>[llm_culling.py]"]
  node_llmprovider["OpenAI culling provider"]
  node_cullingui["Culling review<br/>[culling.js]"]
  node_autoedit["AI editing<br/>[autoedit.py]"]
  node_autocrop["AI crop suggestions<br/>[auto_crop.py]"]
end

subgraph group_data["Album and export"]
  node_album[("Album model<br/>[album.py]")]
  node_albuminfo[("Album metadata<br/>[album_info.py]")]
  node_results["Analysis results<br/>[results.py]"]
  node_albumtools["Album tools<br/>[album-tools.js]"]
  node_export["Keeper export<br/>[apply_export.py]"]
  node_burstvideo["Burst video<br/>[burst_video.py]"]
end

node_photographer(("Photographer"))
node_browser(("Browser UI"))
node_openai["OpenAI API<br/>external service"]

node_photographer -->|"uses"| node_browser
node_browser -->|"opens"| node_webapp
node_webapp -->|"starts import"| node_import
node_browser -->|"configures"| node_team
node_browser -->|"selects album"| node_albumselect
node_import -->|"creates album data"| node_album
node_import -->|"runs analysis"| node_imageanalysis
node_imageanalysis -->|"detects people"| node_detectors
node_imageanalysis -->|"builds frames"| node_frames
node_imageanalysis -->|"supplies detections"| node_grading
node_import -->|"filters jerseys"| node_jersey
node_import -->|"creates previews"| node_annotations
node_import -->|"runs optional ranking"| node_llmstage
node_llmstage -->|"requests rankings"| node_llmprovider
node_llmprovider -.->|"calls API"| node_openai
node_import -->|"records results"| node_results
node_import -->|"updates metadata"| node_albuminfo
node_webapp -->|"serves album data"| node_album
node_browser -->|"reviews photos"| node_cullingui
node_cullingui -.->|"sends review actions"| node_webapp
node_browser -->|"manages faces"| node_faceui
node_webapp -->|"uses recognition"| node_facerec
node_facerec -->|"creates embeddings"| node_facecrop
node_browser -->|"requests edits"| node_autoedit
node_browser -->|"requests crop"| node_autocrop
node_browser -->|"opens tools"| node_albumtools
node_albumtools -->|"exports keepers"| node_export
node_albumtools -->|"creates burst video"| node_burstvideo

click node_webapp "https://github.com/teampixai/teampixpython/blob/main/culling_app.py"
click node_import "https://github.com/teampixai/teampixpython/blob/main/1_prep_review.py"
click node_team "https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/team.js"
click node_albumselect "https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/select-album.js"
click node_album "https://github.com/teampixai/teampixpython/blob/main/algo/album.py"
click node_albuminfo "https://github.com/teampixai/teampixpython/blob/main/algo/album_info.py"
click node_config "https://github.com/teampixai/teampixpython/blob/main/algo/config.py"
click node_imageanalysis "https://github.com/teampixai/teampixpython/blob/main/algo/stages/image_analysis.py"
click node_detectors "https://github.com/teampixai/teampixpython/blob/main/algo/mediapipe_provider.py"
click node_grading "https://github.com/teampixai/teampixpython/blob/main/algo/stages/grading.py"
click node_jersey "https://github.com/teampixai/teampixpython/blob/main/algo/stages/jersey_counting.py"
click node_annotations "https://github.com/teampixai/teampixpython/blob/main/algo/stages/annotation.py"
click node_frames "https://github.com/teampixai/teampixpython/blob/main/algo/frame.py"
click node_results "https://github.com/teampixai/teampixpython/blob/main/algo/results.py"
click node_facerec "https://github.com/teampixai/teampixpython/blob/main/algo/facereco.py"
click node_facecrop "https://github.com/teampixai/teampixpython/blob/main/algo/face_crop_embed.py"
click node_llmstage "https://github.com/teampixai/teampixpython/blob/main/algo/stages/llm_culling.py"
click node_llmprovider "https://github.com/teampixai/teampixpython/blob/main/algo/llm/culling_provider.py"
click node_cullingui "https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/culling.js"
click node_faceui "https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/faces.js"
click node_autoedit "https://github.com/teampixai/teampixpython/blob/main/autoedit.py"
click node_autocrop "https://github.com/teampixai/teampixpython/blob/main/algo/llm/auto_crop.py"
click node_albumtools "https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/album-tools.js"
click node_export "https://github.com/teampixai/teampixpython/blob/main/apply_export.py"
click node_burstvideo "https://github.com/teampixai/teampixpython/blob/main/algo/burst_video.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_import,node_team,node_albumselect,node_browser toneBlue
class node_config,node_imageanalysis,node_detectors,node_grading,node_jersey,node_annotations,node_frames toneAmber
class node_facerec,node_facecrop,node_faceui,node_openai toneMint
class node_llmstage,node_llmprovider,node_cullingui,node_autoedit,node_autocrop toneRose
class node_album,node_albuminfo,node_results,node_albumtools,node_export,node_burstvideo,node_photographer toneIndigo
```

## Components

### Application workflow

- [Local web app](https://github.com/teampixai/teampixpython/blob/main/culling_app.py): `culling_app.py`
- [Photo import](https://github.com/teampixai/teampixpython/blob/main/1_prep_review.py): `1_prep_review.py`
- [Team setup](https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/team.js): `webui/culling/static/js/team.js`
- [Album selection](https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/select-album.js): `webui/culling/static/js/select-album.js`

### Photo analysis

- [Analysis settings](https://github.com/teampixai/teampixpython/blob/main/algo/config.py): `algo/config.py`
- [Image and pose analysis](https://github.com/teampixai/teampixpython/blob/main/algo/stages/image_analysis.py): `algo/stages/image_analysis.py`
- [MediaPipe detection](https://github.com/teampixai/teampixpython/blob/main/algo/mediapipe_provider.py): `algo/mediapipe_provider.py`
- [Face sharpness grading](https://github.com/teampixai/teampixpython/blob/main/algo/stages/grading.py): `algo/stages/grading.py`
- [Jersey filtering](https://github.com/teampixai/teampixpython/blob/main/algo/stages/jersey_counting.py): `algo/stages/jersey_counting.py`
- [Photo annotations](https://github.com/teampixai/teampixpython/blob/main/algo/stages/annotation.py): `algo/stages/annotation.py`
- [Frame data](https://github.com/teampixai/teampixpython/blob/main/algo/frame.py): `algo/frame.py`

### Faces and players

- [Face recognition](https://github.com/teampixai/teampixpython/blob/main/algo/facereco.py): `algo/facereco.py`
- [Face crops and embeddings](https://github.com/teampixai/teampixpython/blob/main/algo/face_crop_embed.py): `algo/face_crop_embed.py`
- [Face management](https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/faces.js): `webui/culling/static/js/faces.js`

### Review and editing

- [Burst ranking and ratings](https://github.com/teampixai/teampixpython/blob/main/algo/stages/llm_culling.py): `algo/stages/llm_culling.py`
- [OpenAI culling provider](https://github.com/teampixai/teampixpython/blob/main/algo/llm/culling_provider.py): `algo/llm/culling_provider.py`
- [Culling review](https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/culling.js): `webui/culling/static/js/culling.js`
- [AI editing](https://github.com/teampixai/teampixpython/blob/main/autoedit.py): `autoedit.py`
- [AI crop suggestions](https://github.com/teampixai/teampixpython/blob/main/algo/llm/auto_crop.py): `algo/llm/auto_crop.py`

### Album and export

- [Album model](https://github.com/teampixai/teampixpython/blob/main/algo/album.py): `algo/album.py`
- [Album metadata](https://github.com/teampixai/teampixpython/blob/main/algo/album_info.py): `algo/album_info.py`
- [Analysis results](https://github.com/teampixai/teampixpython/blob/main/algo/results.py): `algo/results.py`
- [Album tools](https://github.com/teampixai/teampixpython/blob/main/webui/culling/static/js/album-tools.js): `webui/culling/static/js/album-tools.js`
- [Keeper export](https://github.com/teampixai/teampixpython/blob/main/apply_export.py): `apply_export.py`
- [Burst video](https://github.com/teampixai/teampixpython/blob/main/algo/burst_video.py): `algo/burst_video.py`

### Other components

- **Photographer**
- **Browser UI**
- **OpenAI API**: external service

## Connections

- Photographer → Browser UI: uses (evidence: `README.md`)
- Browser UI → Local web app: opens (evidence: `README.md`)
- Local web app → Photo import: starts import (evidence: `culling_app.py`)
- Browser UI → Team setup: configures (evidence: `README.md`)
- Browser UI → Album selection: selects album (evidence: `README.md`)
- Photo import → Album model: creates album data (evidence: `1_prep_review.py`)
- Photo import → Image and pose analysis: runs analysis (evidence: `1_prep_review.py`)
- Image and pose analysis → MediaPipe detection: detects people (evidence: `algo/stages/image_analysis.py`)
- Image and pose analysis → Frame data: builds frames (evidence: `algo/stages/image_analysis.py`)
- Image and pose analysis → Face sharpness grading: supplies detections (evidence: `1_prep_review.py`)
- Photo import → Jersey filtering: filters jerseys (evidence: `1_prep_review.py`)
- Photo import → Photo annotations: creates previews (evidence: `1_prep_review.py`)
- Photo import → Burst ranking and ratings: runs optional ranking (evidence: `1_prep_review.py`)
- Burst ranking and ratings → OpenAI culling provider: requests rankings (evidence: `algo/stages/llm_culling.py`)
- OpenAI culling provider → OpenAI API: calls API (evidence: `README.md`)
- Photo import → Analysis results: records results (evidence: `1_prep_review.py`)
- Photo import → Album metadata: updates metadata (evidence: `1_prep_review.py`)
- Local web app → Album model: serves album data (evidence: `culling_app.py`)
- Browser UI → Culling review: reviews photos (evidence: `README.md`)
- Culling review → Local web app: sends review actions
- Browser UI → Face management: manages faces (evidence: `README.md`)
- Local web app → Face recognition: uses recognition (evidence: `culling_app.py`)
- Face recognition → Face crops and embeddings: creates embeddings (evidence: `algo/facereco.py`)
- Browser UI → AI editing: requests edits (evidence: `README.md`)
- Browser UI → AI crop suggestions: requests crop (evidence: `README.md`)
- Browser UI → Album tools: opens tools (evidence: `README.md`)
- Album tools → Keeper export: exports keepers (evidence: `README.md`)
- Album tools → Burst video: creates burst video (evidence: `README.md`)