# oiibar/animescoreforecast architecture

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

- Interactive diagram: https://gitdiagram.com/oiibar/animescoreforecast
- Repository: https://github.com/oiibar/animescoreforecast

## Overview

This repository is a research project and local application for predicting anime scores from pre-release metadata and synopsis text. The user-facing workflow collects title attributes and synopsis in Streamlit, builds model features, applies saved prediction models, and displays a bounded score. Separate research stages evaluate feature engineering, target-tail strategies, supervised models and ensembles, and unsupervised analyses. Data collection and shared preprocessing support those workflows. Some stage implementation is only partially sampled; edges are limited to imports, calls, and README-documented relationships visible in the evidence.

Main entry points: [`src/exp_common.py`](https://github.com/oiibar/animescoreforecast/blob/main/src/exp_common.py) (Shared experiment data), [`src/features.py`](https://github.com/oiibar/animescoreforecast/blob/main/src/features.py) (Structured features), [`app/app.py`](https://github.com/oiibar/animescoreforecast/blob/main/app/app.py) (Streamlit predictor), [`experiments/e3_models.py`](https://github.com/oiibar/animescoreforecast/blob/main/experiments/e3_models.py) (Model comparisons)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Data collection"]
  node_collector["Score-band collector<br/>[collect_data.py]"]
  node_raw["Raw snapshot<br/>[anime_raw.json]"]
end

subgraph group_shared["Shared data and features"]
  node_processed["Clean dataset<br/>[anime_clean.csv]"]
  node_common["Shared experiment data<br/>[exp_common.py]"]
  node_features["Structured features<br/>[features.py]"]
  node_text["Synopsis cleaning and embeddings<br/>[text_features.py]"]
end

subgraph group_research["Model research"]
  node_e1["Feature experiments<br/>[e1_features.py]"]
  node_e2["Target-tail experiments<br/>[e2_target.py]"]
  node_e3["Model comparisons<br/>[e3_models.py]"]
  node_e4["Unsupervised analysis<br/>[e4_unsupervised.py]"]
  node_v1["Final model checks<br/>[v1_check.py]"]
end

subgraph group_application["Prediction application"]
  node_models[("Saved prediction models<br/>[final_model.joblib]")]
  node_app["Streamlit predictor<br/>[app.py]"]
  node_result["Predicted score<br/>[app.py]"]
end

node_user(("User"))
node_anilist{{"AniList API"}}

node_collector -->|"queries"| node_anilist
node_collector -->|"writes snapshot"| node_raw
node_app -->|"loads data"| node_common
node_app -->|"builds input"| node_features
node_features -->|"uses preprocessing"| node_common
node_features -.->|"cleans synopsis"| node_text
node_common -->|"imports cleaner"| node_text
node_e1 -->|"uses shared data"| node_common
node_e1 -->|"tests features"| node_features
node_e2 -->|"runs validation"| node_common
node_e3 -->|"runs comparisons"| node_common
node_e3 -->|"uses feature prep"| node_features
node_e4 -->|"runs analysis"| node_common
node_v1 -->|"imports models"| node_e3
node_v1 -->|"checks features"| node_features
node_user -->|"enters inputs"| node_app
node_app -.->|"predicts with"| node_models
node_app -->|"displays score"| node_result
node_raw -.->|"prepared dataset"| node_processed
node_processed -.->|"loads dataset"| node_common

click node_collector "https://github.com/oiibar/animescoreforecast/blob/main/scripts/collect_data.py"
click node_raw "https://github.com/oiibar/animescoreforecast/blob/main/data/raw/anime_raw.json"
click node_processed "https://github.com/oiibar/animescoreforecast/blob/main/data/processed/anime_clean.csv"
click node_common "https://github.com/oiibar/animescoreforecast/blob/main/src/exp_common.py"
click node_features "https://github.com/oiibar/animescoreforecast/blob/main/src/features.py"
click node_text "https://github.com/oiibar/animescoreforecast/blob/main/src/text_features.py"
click node_e1 "https://github.com/oiibar/animescoreforecast/blob/main/experiments/e1_features.py"
click node_e2 "https://github.com/oiibar/animescoreforecast/blob/main/experiments/e2_target.py"
click node_e3 "https://github.com/oiibar/animescoreforecast/blob/main/experiments/e3_models.py"
click node_e4 "https://github.com/oiibar/animescoreforecast/blob/main/experiments/e4_unsupervised.py"
click node_v1 "https://github.com/oiibar/animescoreforecast/blob/main/experiments/v1_check.py"
click node_models "https://github.com/oiibar/animescoreforecast/blob/main/models/final_model.joblib"
click node_app "https://github.com/oiibar/animescoreforecast/blob/main/app/app.py"
click node_result "https://github.com/oiibar/animescoreforecast/blob/main/app/app.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_collector,node_raw,node_user toneBlue
class node_processed,node_common,node_features,node_text toneAmber
class node_e1,node_e2,node_e3,node_e4,node_v1,node_anilist toneMint
class node_models,node_app,node_result toneRose
```

## Components

### Data collection

- [Score-band collector](https://github.com/oiibar/animescoreforecast/blob/main/scripts/collect_data.py): `scripts/collect_data.py`
- [Raw snapshot](https://github.com/oiibar/animescoreforecast/blob/main/data/raw/anime_raw.json): `data/raw/anime_raw.json`

### Shared data and features

- [Clean dataset](https://github.com/oiibar/animescoreforecast/blob/main/data/processed/anime_clean.csv): `data/processed/anime_clean.csv`
- [Shared experiment data](https://github.com/oiibar/animescoreforecast/blob/main/src/exp_common.py): `src/exp_common.py`
- [Structured features](https://github.com/oiibar/animescoreforecast/blob/main/src/features.py): `src/features.py`
- [Synopsis cleaning and embeddings](https://github.com/oiibar/animescoreforecast/blob/main/src/text_features.py): `src/text_features.py`

### Model research

- [Feature experiments](https://github.com/oiibar/animescoreforecast/blob/main/experiments/e1_features.py): `experiments/e1_features.py`
- [Target-tail experiments](https://github.com/oiibar/animescoreforecast/blob/main/experiments/e2_target.py): `experiments/e2_target.py`
- [Model comparisons](https://github.com/oiibar/animescoreforecast/blob/main/experiments/e3_models.py): `experiments/e3_models.py`
- [Unsupervised analysis](https://github.com/oiibar/animescoreforecast/blob/main/experiments/e4_unsupervised.py): `experiments/e4_unsupervised.py`
- [Final model checks](https://github.com/oiibar/animescoreforecast/blob/main/experiments/v1_check.py): `experiments/v1_check.py`

### Prediction application

- [Saved prediction models](https://github.com/oiibar/animescoreforecast/blob/main/models/final_model.joblib): `models/final_model.joblib`
- [Streamlit predictor](https://github.com/oiibar/animescoreforecast/blob/main/app/app.py): `app/app.py`
- [Predicted score](https://github.com/oiibar/animescoreforecast/blob/main/app/app.py): `app/app.py`

### Other components

- **User**
- **AniList API**

## Connections

- Score-band collector → AniList API: queries (evidence: `scripts/collect_data.py`)
- Score-band collector → Raw snapshot: writes snapshot (evidence: `scripts/collect_data.py`)
- Streamlit predictor → Shared experiment data: loads data (evidence: `app/app.py`)
- Streamlit predictor → Structured features: builds input (evidence: `app/app.py`)
- Structured features → Shared experiment data: uses preprocessing (evidence: `src/features.py`)
- Structured features → Synopsis cleaning and embeddings: cleans synopsis (evidence: `src/features.py`)
- Shared experiment data → Synopsis cleaning and embeddings: imports cleaner (evidence: `src/exp_common.py`)
- Feature experiments → Shared experiment data: uses shared data (evidence: `experiments/e1_features.py`)
- Feature experiments → Structured features: tests features (evidence: `experiments/e1_features.py`)
- Target-tail experiments → Shared experiment data: runs validation (evidence: `experiments/e2_target.py`)
- Model comparisons → Shared experiment data: runs comparisons (evidence: `experiments/e3_models.py`)
- Model comparisons → Structured features: uses feature prep (evidence: `experiments/e3_models.py`)
- Unsupervised analysis → Shared experiment data: runs analysis (evidence: `experiments/e4_unsupervised.py`)
- Final model checks → Model comparisons: imports models (evidence: `experiments/v1_check.py`)
- Final model checks → Structured features: checks features (evidence: `experiments/v1_check.py`)
- User → Streamlit predictor: enters inputs (evidence: `README.md`)
- Streamlit predictor → Saved prediction models: predicts with
- Streamlit predictor → Predicted score: displays score (evidence: `app/app.py`)
- Raw snapshot → Clean dataset: prepared dataset
- Clean dataset → Shared experiment data: loads dataset
