# tensorflow/tensor2tensor architecture

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

- Interactive diagram: https://gitdiagram.com/tensorflow/tensor2tensor
- Repository: https://github.com/tensorflow/tensor2tensor

## Overview

##### Project type and purpose
- Tensor2Tensor is a modular deep-learning framework and toolkit:
- Offers CLI entrypoints (t2t-datagen, t2t-trainer, t2t-decoder, etc.)
- Provides reusable components—Problems (data), Models, Layers, Hyperparams, Utils
- Supports training, evaluation, inference, model export, and web-based “insights” visualization
- Integrates with TensorFlow, Cloud ML Engine, TPUs, distributed setups

##### File structure
- Top-level files: setup.py, README.md, configuration (travis, pylintrc, floyd.yml)
- Directories and roles:
- tensor2tensor/bin → CLI scripts (entrypoints)
- tensor2tensor/data_generators → Problem definitions & TFRecord data pipeline
- tensor2tensor/models → Model implementations (Transformer, ResNet, research)
- tensor2tensor/layers → Reusable NN layers (attention, Transformer components)
- tensor2tensor/utils → Registry, HParams, trainer_lib, checkpoint hooks, metrics, TFRecord readers
- tensor2tensor/serving → SavedModel export & inference API
- tensor2tensor/insights → Query processor, web server, Polymer front-end UI
- Other: notebooks, docs, oss_scripts, test_data

##### Extract architecture hints from the README
- Core concepts: Problems ↔ Models ↔ Hyperparam sets, all registered via a central registry
- Binaries: t2t-datagen (data prep), t2t-trainer (train/eval/infer), t2t-decoder/bleu/exporter
- Deployment targets: local GPUs, multi-GPU with parameter servers, Cloud ML Engine, Cloud TPU
- Serving & Insights components for production inference and monitoring

##### Main components and their interactions
a. CLI layer
- t2t-datagen → invokes Data Generator registry → writes TFRecord files to DataDir
- t2t-trainer → uses registry to instantiate Problem, Model, HParams → builds TF graph → trains/evaluates via TensorFlow → writes checkpoints + summaries
- t2t-decoder / t2t-exporter → load checkpoints + graph → produce translations or SavedModel
b. Core library
- Registry service (problems, models, hparams)
- DataGenerators (produce TFExample → TFRecord)
- Layers & Modalities (bottom/top transformations)
- Models (tensor-to-tensor graphs)
- Utils (trainer_lib for session management, beam search, metrics, checkpoint compat)
c. Storage & compute
- Data storage: TFRecord files on disk or cloud storage
- Checkpoints: model.ckpt in OutputDir
- Logs/summaries: TensorBoard–readable event files
- Compute backends: local GPU(s), parameter servers, Cloud TPU pods, Cloud ML Engine
d. Serving & Insights
- Serving: export.py → SavedModel → query.py serves inference requests
- Insights: query_processor loads metrics & checkpoints → insights/server (Python) → Polymer-based front-end (HTML/JS)

##### Architectural patterns & design principles
- Plugin/registry pattern: loose coupling of Problems, Models, HParams via central registry
- Layered architecture: clear separation of CLI, core library, data layer, compute layer, serving layer, and visualization/UI
- MVC (or MV*) in Insights: server/controller, query_processor/model, Polymer frontend/view
- Modular & extensible: add new Problems, Models, hyperparam sets without core code changes

##### Technologies and external services
- Python, TensorFlow (and tf.data, tf.estimator or low-level APIs)
- TFRecord + proto buffers
- REST or RPC (for serving/query)
- JavaScript + Polymer for UI
- Cloud ML Engine, Cloud TPU, parameter-server / multi-worker distributed TensorFlow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Binaries"
        direction TB
        t2t_datagen["t2t-datagen"]:::cli
        t2t_trainer["t2t-trainer"]:::cli
        t2t_decoder["t2t-decoder / t2t-exporter"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Registry["Registry Service"]:::core
        DataGenerators["Data Generators (Problems)"]:::core
        Models["Model Implementations"]:::core
        Layers["NN Layers & Modalities"]:::core
        HParams["Hyperparameter Management"]:::core
        TrainerLib["Trainer Library"]:::core
        Utils["Utility Functions"]:::core
        Problems["Problem Registry & Utilities"]:::core
        Envs["Environment-based Problems"]:::core
    end

    %% Storage & Compute
    subgraph "Storage & Compute"
        direction TB
        TFRecord["TFRecord Files"]:::storage
        ComputeBackend["Compute Backend"]:::compute
        Checkpoints["Checkpoints"]:::storage
        Summaries["Summaries / Event Files"]:::storage
    end

    %% Serving & Insights
    subgraph "Serving & Insights"
        direction TB
        ExportSM["SavedModel Export"]:::serving
        ServingAPI["Inference API"]:::serving
        InsightsProcessor["Insights Query Processor"]:::insights
        PolymerUI["Polymer Front-End UI"]:::insights
    end

    %% Data Flow
    RawData((Raw Data)):::external -->|generate_data| t2t_datagen
    t2t_datagen -->|writes TFRecord| TFRecord
    TFRecord -->|train_step| t2t_trainer
    t2t_trainer -->|builds graph using| Registry
    Registry --> DataGenerators
    Registry --> Models
    Registry --> HParams
    t2t_trainer -->|runs on| ComputeBackend
    ComputeBackend -->|outputs| Checkpoints
    ComputeBackend -->|outputs| Summaries
    Checkpoints -->|load for export| t2t_decoder
    t2t_decoder -->|produces| ExportSM
    ExportSM -->|serves via| ServingAPI
    Summaries -->|queried by| InsightsProcessor
    InsightsProcessor -->|serves data to| PolymerUI

    %% Additional Core Links
    DataGenerators -->|produces TFExamples| TFRecord
    Models -->|use Layers & Modalities| Layers
    TrainerLib -->|manages sessions & hooks| ComputeBackend
    Utils -->|includes BLEU, beam search, checkpoint hooks| TrainerLib
    Problems -->|registers via| Registry
    Envs -->|registers via| Registry

    %% Click Events
    click t2t_datagen "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/bin/"
    click t2t_trainer "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/bin/"
    click t2t_decoder "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/bin/"
    click DataGenerators "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/data_generators/"
    click Registry "https://github.com/tensorflow/tensor2tensor/blob/master/tensor2tensor/utils/registry.py"
    click HParams "https://github.com/tensorflow/tensor2tensor/blob/master/tensor2tensor/utils/hparam.py"
    click HParams "https://github.com/tensorflow/tensor2tensor/blob/master/tensor2tensor/utils/hparams_lib.py"
    click TrainerLib "https://github.com/tensorflow/tensor2tensor/blob/master/tensor2tensor/utils/trainer_lib.py"
    click Utils "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/utils/"
    click Models "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/models/"
    click Layers "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/layers/"
    click ExportSM "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/serving/"
    click ServingAPI "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/serving/"
    click InsightsProcessor "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/insights/"
    click PolymerUI "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/insights/polymer/"
    click Visualization "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/visualization/"
    click Problems "https://github.com/tensorflow/tensor2tensor/blob/master/tensor2tensor/problems.py"
    click Envs "https://github.com/tensorflow/tensor2tensor/tree/master/tensor2tensor/envs/"

    %% Styles
    classDef cli fill:#FFD580,stroke:#333,stroke-width:1px
    classDef core fill:#A0D3E8,stroke:#333,stroke-width:1px
    classDef storage fill:#FFC0CB,stroke:#333,stroke-width:1px
    classDef compute fill:#C3FDB8,stroke:#333,stroke-width:1px
    classDef serving fill:#FFB347,stroke:#333,stroke-width:1px
    classDef insights fill:#C0C0C0,stroke:#333,stroke-width:1px
    classDef external fill:#E3E4FA,stroke:#333,stroke-width:1px
    classDef frontend fill:#D5E8D4,stroke:#333,stroke-width:1px
    class t2t_datagen,t2t_trainer,t2t_decoder cli
    class Registry,DataGenerators,Models,Layers,HParams,TrainerLib,Utils,Problems,Envs core
    class TFRecord,Checkpoints,Summaries storage
    class ComputeBackend compute
    class ExportSM,ServingAPI serving
    class InsightsProcessor,PolymerUI insights
    class RawData external
```
