# kseto06/otakunet architecture

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

- Interactive diagram: https://gitdiagram.com/kseto06/otakunet
- Repository: https://github.com/kseto06/otakunet

## Overview

1. **Overall shape**
   OtakuNet is split into two clear boundaries: an **offline model-training subsystem** and an **online desktop GUI inference subsystem**. The training side produces serialized model artifacts; the GUI side loads those artifacts and turns user genre ratings into anime recommendations.

2. **Training and experimentation layer**
   The `notebooks/` directory is the model development area. `ContentBasedAnime.ipynb` appears to contain the data preparation, feature engineering, training, and evaluation workflow for the recommender. This is where the content-based logic is built and the learned parameters are exported.

3. **Custom neural-network framework**
   The `framework/` package is the core ML engine. `framework.py`, `model.py`, and `Sequential.py` indicate a from-scratch neural network abstraction built on top of NumPy rather than a full ML library. This suggests a lightweight training/inference runtime with custom layers, sequential composition, and model orchestration.

4. **Dual-network recommendation model**
   The README describes a **dual neural network architecture**: one path learns user-related features and another learns anime-related features, then the learned representations are combined for the final prediction. Architecturally, this means the model has two parallel input branches and a merge/scoring stage rather than a single monolithic classifier.

5. **Feature engineering and preprocessing**
   The model relies on data preparation steps such as **Bayesian rating, weighted average, and z-score normalization**. The presence of `item_prepared.pkl`, `item_original.pkl`, `y_original.pkl`, and `user_constants.pkl` shows that preprocessing outputs are persisted separately from raw/normalized targets and constants used at inference time.

6. **Persisted model artifacts**
   The `notebooks/pickle/` directory is the handoff point from training to application. `item_model.pkl`, `user_model.pkl`, and the related pickle files indicate the GUI does not retrain the model; it consumes precomputed parameters and prepared data structures for prediction.

7. **GUI application boundary**
   The `gui/` directory is a standalone desktop application. `gui/app.py` is the entry point, and `gui/views/` contains the screens: `Home.py`, `Prompt.py`, and `Recommend.py`. This is a multi-screen local UI rather than a browser app.

8. **User interaction flow**
   The GUI flow is: start on the home screen, move to the prompt screen to collect genre ratings, then navigate to the recommend screen to display results. This makes the user input a compact vector of preferences that feeds the inference pipeline.

9. **Prediction and ranking pipeline**
   `gui/functions/predictions.py` is the bridge between UI and model artifacts. It likely loads the serialized models, converts prompt inputs into model-ready form, computes candidate anime scores, sorts them, and returns the top recommendations with metadata for display.

10. **Presentation layer for recommendations**
   The recommend screen is responsible for rendering the final ranked output: anime names, genres, and images. The `gui/views/images/` folder and `demo/` animation indicate the app has a presentation-focused layer separate from the prediction logic.

11. **Technology stack**
   The ML side is centered on **NumPy** and **Pandas**, with pickle-based serialization for model persistence. The UI side uses **customtkinter** per the README and has its own environment requirements in `gui/requirements.txt`. The repo is therefore a mix of Python ML tooling and a native desktop interface.

12. **Key architecture diagram emphasis**
   If you draw this repo, the most important arrows are:
   - raw anime/user data → notebook preprocessing/training
   - preprocessing/training → custom NumPy framework
   - trained parameters → pickle artifacts
   - GUI prompt inputs → prediction function
   - prediction function + pickles → ranked recommendations → UI display  
   The main architectural boundary is between **model generation** and **model consumption**.

Main entry points: [`notebooks/ContentBasedAnime.ipynb`](https://github.com/kseto06/otakunet/blob/main/notebooks/ContentBasedAnime.ipynb) (ContentBasedAnime), [`gui/functions/predictions.py`](https://github.com/kseto06/otakunet/blob/main/gui/functions/predictions.py) (Predictions), [`framework/framework.py`](https://github.com/kseto06/otakunet/blob/main/framework/framework.py) (Framework core), [`gui/views/Home.py`](https://github.com/kseto06/otakunet/blob/main/gui/views/Home.py) (Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Offline training"]
  node_notebook["ContentBasedAnime<br/>training notebook"]
end

subgraph group_framework["ML framework"]
  node_fw_core["Framework core<br/>neural runtime<br/>[framework.py]"]
  node_fw_model["Model base<br/>model orchestration<br/>[model.py]"]
  node_fw_seq["Sequential<br/>layer composition<br/>[Sequential.py]"]
end

subgraph group_gui["Desktop app"]
  node_gui_app["App entry<br/>desktop launcher<br/>[app.py]"]
  node_gui_home["Home<br/>landing screen<br/>[Home.py]"]
  node_gui_prompt["Prompt<br/>input screen<br/>[Prompt.py]"]
  node_gui_recommend["Recommend<br/>results screen<br/>[Recommend.py]"]
  node_gui_pred["Predictions<br/>inference bridge<br/>[predictions.py]"]
end

subgraph group_artifacts["Model artifacts"]
  node_item_model[("Item model<br/>trained artifact<br/>[item_model.pkl]")]
  node_user_model[("User model<br/>trained artifact<br/>[user_model.pkl]")]
  node_item_prepared[("Prepared items<br/>preprocessed data<br/>[item_prepared.pkl]")]
  node_item_original[("Raw items<br/>source data<br/>[item_original.pkl]")]
  node_user_constants[("User constants<br/>feature constants<br/>[user_constants.pkl]")]
  node_y_original[("Original targets<br/>target data<br/>[y_original.pkl]")]
end

node_readme["README<br/>project overview<br/>[README.md]"]

node_readme -->|"describes"| node_notebook
node_notebook -->|"uses"| node_fw_core
node_fw_core -->|"includes"| node_fw_model
node_fw_core -->|"includes"| node_fw_seq
node_notebook -->|"writes"| node_item_prepared
node_notebook -->|"writes"| node_item_model
node_notebook -->|"writes"| node_user_model
node_notebook -->|"writes"| node_user_constants
node_notebook -->|"reads"| node_item_original
node_notebook -->|"reads"| node_y_original
node_gui_app -->|"opens"| node_gui_home
node_gui_home -->|"navigates"| node_gui_prompt
node_gui_prompt -->|"submits"| node_gui_pred
node_gui_pred -->|"loads"| node_item_model
node_gui_pred -->|"loads"| node_user_model
node_gui_pred -->|"loads"| node_item_prepared
node_gui_pred -->|"loads"| node_user_constants
node_gui_pred -->|"returns"| node_gui_recommend
node_gui_recommend -.->|"restart"| node_gui_home

click node_readme "https://github.com/kseto06/otakunet/blob/main/README.md"
click node_notebook "https://github.com/kseto06/otakunet/blob/main/notebooks/ContentBasedAnime.ipynb"
click node_fw_core "https://github.com/kseto06/otakunet/blob/main/framework/framework.py"
click node_fw_model "https://github.com/kseto06/otakunet/blob/main/framework/model.py"
click node_fw_seq "https://github.com/kseto06/otakunet/blob/main/framework/Sequential.py"
click node_gui_app "https://github.com/kseto06/otakunet/blob/main/gui/app.py"
click node_gui_home "https://github.com/kseto06/otakunet/blob/main/gui/views/Home.py"
click node_gui_prompt "https://github.com/kseto06/otakunet/blob/main/gui/views/Prompt.py"
click node_gui_recommend "https://github.com/kseto06/otakunet/blob/main/gui/views/Recommend.py"
click node_gui_pred "https://github.com/kseto06/otakunet/blob/main/gui/functions/predictions.py"
click node_item_model "https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/item_model.pkl"
click node_user_model "https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/user_model.pkl"
click node_item_prepared "https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/item_prepared.pkl"
click node_item_original "https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/item_original.pkl"
click node_user_constants "https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/user_constants.pkl"
click node_y_original "https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/y_original.pkl"

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_notebook toneBlue
class node_fw_core,node_fw_model,node_fw_seq toneAmber
class node_gui_app,node_gui_home,node_gui_prompt,node_gui_recommend,node_gui_pred toneMint
class node_item_model,node_user_model,node_item_prepared,node_item_original,node_user_constants,node_y_original toneRose
class node_readme toneNeutral
```

## Components

### Offline training

Notebook-driven model development, preprocessing, and serialized artifact generation.

- [ContentBasedAnime](https://github.com/kseto06/otakunet/blob/main/notebooks/ContentBasedAnime.ipynb): training notebook · Main experimentation and training workflow for the content-based recommender. · `notebooks/ContentBasedAnime.ipynb`

### ML framework

Custom NumPy-based neural-network runtime used by the recommender model.

- [Framework core](https://github.com/kseto06/otakunet/blob/main/framework/framework.py): neural runtime · Top-level custom ML framework abstractions built around NumPy. · `framework/framework.py`
- [Model base](https://github.com/kseto06/otakunet/blob/main/framework/model.py): model orchestration · Model lifecycle and shared training/inference behavior. · `framework/model.py`
- [Sequential](https://github.com/kseto06/otakunet/blob/main/framework/Sequential.py): layer composition · Sequential composition helper for stacking network components. · `framework/Sequential.py`

### Desktop app

Local multi-screen GUI that collects ratings and shows ranked anime recommendations.

- [App entry](https://github.com/kseto06/otakunet/blob/main/gui/app.py): desktop launcher · Starts the customtkinter application and screen flow. · `gui/app.py`
- [Home](https://github.com/kseto06/otakunet/blob/main/gui/views/Home.py): landing screen · Initial screen that begins the user journey. · `gui/views/Home.py`
- [Prompt](https://github.com/kseto06/otakunet/blob/main/gui/views/Prompt.py): input screen · Collects genre ratings and prepares user preferences. · `gui/views/Prompt.py`
- [Recommend](https://github.com/kseto06/otakunet/blob/main/gui/views/Recommend.py): results screen · Displays ranked anime recommendations with metadata and images. · `gui/views/Recommend.py`
- [Predictions](https://github.com/kseto06/otakunet/blob/main/gui/functions/predictions.py): inference bridge · Loads serialized models, transforms prompt input, scores candidates, and ranks results. · `gui/functions/predictions.py`

### Model artifacts

Persisted pickle files consumed by the GUI at inference time.

- [Item model](https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/item_model.pkl): trained artifact · Serialized anime-side model parameters used during inference. · `notebooks/pickle/item_model.pkl`
- [User model](https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/user_model.pkl): trained artifact · Serialized user-side model parameters used during inference. · `notebooks/pickle/user_model.pkl`
- [Prepared items](https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/item_prepared.pkl): preprocessed data · Anime feature data prepared for training and inference. · `notebooks/pickle/item_prepared.pkl`
- [Raw items](https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/item_original.pkl): source data · Original anime item data preserved alongside prepared features. · `notebooks/pickle/item_original.pkl`
- [User constants](https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/user_constants.pkl): feature constants · Normalization and scoring constants reused at inference time. · `notebooks/pickle/user_constants.pkl`
- [Original targets](https://github.com/kseto06/otakunet/blob/main/notebooks/pickle/y_original.pkl): target data · Stored target values or labels associated with the training workflow. · `notebooks/pickle/y_original.pkl`

### Other components

- [README](https://github.com/kseto06/otakunet/blob/main/README.md): project overview · Describes the dual-network recommender, training flow, and GUI usage. · `README.md`

## Connections

- README → ContentBasedAnime: describes · The README documents the training workflow and model design.
- ContentBasedAnime → Framework core: uses · Notebook training relies on the custom NumPy framework.
- Framework core → Model base: includes · Core framework builds on model lifecycle abstractions.
- Framework core → Sequential: includes · Core framework includes sequential composition support.
- ContentBasedAnime → Prepared items: writes · Training produces prepared item features for reuse.
- ContentBasedAnime → Item model: writes · Training exports the anime-side learned parameters.
- ContentBasedAnime → User model: writes · Training exports the user-side learned parameters.
- ContentBasedAnime → User constants: writes · Training persists normalization and scoring constants.
- ContentBasedAnime → Raw items: reads · Training consumes original anime data.
- ContentBasedAnime → Original targets: reads · Training consumes original target values.
- App entry → Home: opens · The application starts on the home screen.
- Home → Prompt: navigates · Users move from the home screen to the prompt screen.
- Prompt → Predictions: submits · User ratings are handed off to the prediction bridge.
- Predictions → Item model: loads · Inference loads the item-side serialized model.
- Predictions → User model: loads · Inference loads the user-side serialized model.
- Predictions → Prepared items: loads · Inference uses prepared anime features and metadata.
- Predictions → User constants: loads · Inference reuses stored constants for feature shaping.
- Predictions → Recommend: returns · Prediction results are sent to the recommendation screen.
- Recommend → Home: restart · The UI can return to the start of the flow.
