# imannil/pet-act-vision architecture

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

- Interactive diagram: https://gitdiagram.com/imannil/pet-act-vision
- Repository: https://github.com/imannil/pet-act-vision

## Overview

PetActVision classifies pet activities in short videos. Its primary user workflow is upload in the Next.js interface, submit to FastAPI, decode and normalize a frame sequence, run the CNN-plus-temporal classifier, and return a label, probabilities, explanation, and preview frames. Offline preparation, training, and evaluation form a separate model-development workflow. The README documents dataset downloading and Docker support, but sampled code does not establish their runtime wiring; the graph therefore omits uncertain links and deployment machinery.

Main entry points: [`src/inference/predict.py`](https://github.com/imannil/pet-act-vision/blob/main/src/inference/predict.py) (Inference orchestration), [`src/api/main.py`](https://github.com/imannil/pet-act-vision/blob/main/src/api/main.py) (FastAPI endpoints), [`src/models/evaluate_model.py`](https://github.com/imannil/pet-act-vision/blob/main/src/models/evaluate_model.py) (Model evaluation), [`src/data/preprocess_video.py`](https://github.com/imannil/pet-act-vision/blob/main/src/data/preprocess_video.py) (Video preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webui["Upload and results UI<br/>[page.tsx]"]
end

subgraph group_serving["Prediction service"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_inference["Inference orchestration<br/>[predict.py]"]
end

subgraph group_ml["Model pipeline"]
  node_frames["Frame extraction<br/>[extract_frames.py]"]
  node_classifier["CNN temporal model<br/>[video_model.py]"]
  node_checkpoint[("Model checkpoint")]
  node_training["Model training<br/>[train_model.py]"]
  node_evaluation["Model evaluation<br/>[evaluate_model.py]"]
  node_metrics["Evaluation metrics"]
end

subgraph group_data["Dataset preparation"]
  node_rawvideos[("Labeled raw videos")]
  node_preprocess["Video preprocessing"]
  node_processed[("Sequences and manifest")]
  node_dataset["Dataset loading<br/>[dataset.py]"]
  node_download["Dataset acquisition"]
end

node_user(("Video uploader"))

node_user -->|"uploads video"| node_webui
node_webui -->|"POST /predict"| node_api
node_api -->|"predicts video"| node_inference
node_api -->|"extracts previews"| node_inference
node_inference -->|"loads weights"| node_checkpoint
node_inference -->|"extracts and normalizes"| node_frames
node_inference -->|"runs prediction"| node_classifier
node_api -->|"returns results"| node_webui
node_rawvideos -->|"reads clips"| node_preprocess
node_preprocess -->|"extracts sequences"| node_frames
node_preprocess -->|"writes sequences and manifest"| node_processed
node_preprocess -->|"writes label map"| node_processed
node_processed -->|"reads manifest and samples"| node_dataset
node_dataset -->|"provides batches"| node_training
node_training -->|"trains model"| node_classifier
node_training -->|"saves best weights"| node_checkpoint
node_processed -->|"reads manifest and samples"| node_evaluation
node_evaluation -->|"evaluates model"| node_classifier
node_evaluation -->|"loads weights"| node_checkpoint
node_evaluation -->|"writes confusion matrix"| node_metrics
node_download -.->|"acquires data"| node_rawvideos

click node_webui "https://github.com/imannil/pet-act-vision/blob/main/frontend/src/app/page.tsx"
click node_api "https://github.com/imannil/pet-act-vision/blob/main/src/api/main.py"
click node_inference "https://github.com/imannil/pet-act-vision/blob/main/src/inference/predict.py"
click node_frames "https://github.com/imannil/pet-act-vision/blob/main/src/features/extract_frames.py"
click node_classifier "https://github.com/imannil/pet-act-vision/blob/main/src/models/video_model.py"
click node_checkpoint "https://github.com/imannil/pet-act-vision/tree/main/models"
click node_rawvideos "https://github.com/imannil/pet-act-vision/tree/main/data/raw"
click node_preprocess "https://github.com/imannil/pet-act-vision/blob/main/src/data/preprocess_video.py"
click node_processed "https://github.com/imannil/pet-act-vision/tree/main/data/processed"
click node_dataset "https://github.com/imannil/pet-act-vision/blob/main/src/data/dataset.py"
click node_training "https://github.com/imannil/pet-act-vision/blob/main/src/models/train_model.py"
click node_evaluation "https://github.com/imannil/pet-act-vision/blob/main/src/models/evaluate_model.py"
click node_download "https://github.com/imannil/pet-act-vision/blob/main/src/data/download_dataset.py"
click node_metrics "https://github.com/imannil/pet-act-vision/tree/main/models"

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_webui toneBlue
class node_api,node_inference toneAmber
class node_frames,node_classifier,node_checkpoint,node_training,node_evaluation,node_metrics toneMint
class node_rawvideos,node_preprocess,node_processed,node_dataset,node_download toneRose
class node_user toneIndigo
```

## Components

### Web experience

- [Upload and results UI](https://github.com/imannil/pet-act-vision/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`

### Prediction service

- [FastAPI endpoints](https://github.com/imannil/pet-act-vision/blob/main/src/api/main.py): `src/api/main.py`
- [Inference orchestration](https://github.com/imannil/pet-act-vision/blob/main/src/inference/predict.py): `src/inference/predict.py`

### Model pipeline

- [Frame extraction](https://github.com/imannil/pet-act-vision/blob/main/src/features/extract_frames.py): `src/features/extract_frames.py`
- [CNN temporal model](https://github.com/imannil/pet-act-vision/blob/main/src/models/video_model.py): `src/models/video_model.py`
- [Model checkpoint](https://github.com/imannil/pet-act-vision/tree/main/models): `models`
- [Model training](https://github.com/imannil/pet-act-vision/blob/main/src/models/train_model.py): `src/models/train_model.py`
- [Model evaluation](https://github.com/imannil/pet-act-vision/blob/main/src/models/evaluate_model.py): `src/models/evaluate_model.py`
- [Evaluation metrics](https://github.com/imannil/pet-act-vision/tree/main/models): `models`

### Dataset preparation

- [Labeled raw videos](https://github.com/imannil/pet-act-vision/tree/main/data/raw): `data/raw`
- [Video preprocessing](https://github.com/imannil/pet-act-vision/blob/main/src/data/preprocess_video.py): `src/data/preprocess_video.py`
- [Sequences and manifest](https://github.com/imannil/pet-act-vision/tree/main/data/processed): `data/processed`
- [Dataset loading](https://github.com/imannil/pet-act-vision/blob/main/src/data/dataset.py): `src/data/dataset.py`
- [Dataset acquisition](https://github.com/imannil/pet-act-vision/blob/main/src/data/download_dataset.py): `src/data/download_dataset.py`

### Other components

- **Video uploader**

## Connections

- Video uploader → Upload and results UI: uploads video
- Upload and results UI → FastAPI endpoints: POST /predict
- FastAPI endpoints → Inference orchestration: predicts video
- FastAPI endpoints → Inference orchestration: extracts previews
- Inference orchestration → Model checkpoint: loads weights
- Inference orchestration → Frame extraction: extracts and normalizes
- Inference orchestration → CNN temporal model: runs prediction
- FastAPI endpoints → Upload and results UI: returns results
- Labeled raw videos → Video preprocessing: reads clips
- Video preprocessing → Frame extraction: extracts sequences
- Video preprocessing → Sequences and manifest: writes sequences and manifest
- Video preprocessing → Sequences and manifest: writes label map
- Sequences and manifest → Dataset loading: reads manifest and samples
- Dataset loading → Model training: provides batches
- Model training → CNN temporal model: trains model
- Model training → Model checkpoint: saves best weights
- Sequences and manifest → Model evaluation: reads manifest and samples
- Model evaluation → CNN temporal model: evaluates model
- Model evaluation → Model checkpoint: loads weights
- Model evaluation → Evaluation metrics: writes confusion matrix
- Dataset acquisition → Labeled raw videos: acquires data