Architecture

This page is a top-down map of how TensorFlow's pieces fit together. Each named subsystem links to a dedicated page for details.

Major layers

graph TD
    subgraph Frontends
        Py[Python API]
        Cpp[C++ API]
        C[C API]
        Java[Java/Android]
        Go[Go]
        JS[JS converter]
    end

    subgraph Core
        Eager[Eager runtime]
        Graph[Graph execution]
        Kernels[Op kernels]
        Devices[Device layer]
        Distributed[Distributed runtime]
    end

    subgraph Compiler
        Grappler[Grappler optimizer]
        XLA[XLA bridge / HLO]
        MLIR[MLIR passes]
        TF2TRT[TensorRT integration]
    end

    subgraph Edge
        Lite[TFLite interpreter]
        Micro[TFLite Micro]
        Delegates[GPU/NNAPI/XNNPACK delegates]
    end

    Py --> Eager
    Py --> Graph
    Cpp --> Graph
    C --> Eager
    C --> Graph
    Java --> C
    Go --> C
    Eager --> Kernels
    Graph --> Grappler
    Grappler --> Kernels
    Graph --> XLA
    XLA --> MLIR
    XLA --> Kernels
    Kernels --> Devices
    Graph --> Distributed
    Py -- SavedModel export --> Lite
    Lite --> Delegates
    Lite --> Micro

Layer-by-layer

Frontends (tensorflow/python/, tensorflow/cc/, tensorflow/c/, tensorflow/java/, tensorflow/go/, tensorflow/js/)

The frontends construct ops and tensors and call into the core. The Python frontend is the largest and most feature-complete; the C API (tensorflow/c/c_api.h) is the stable ABI that other languages bind to. See apps.

Core runtime (tensorflow/core/)

The runtime is C++ and split into:

• Framework (tensorflow/core/framework/) — OpKernel, Tensor, OpDef, type system, allocator interfaces, Resource/ResourceMgr.
• Common runtime (tensorflow/core/common_runtime/) — direct session, executor, placer, device manager, function library, eager service.
• Distributed runtime (tensorflow/core/distributed_runtime/) — gRPC master/worker, rendezvous, parameter-server-style coordination.
• Kernels (tensorflow/core/kernels/) — ~10 000 C++ files implementing the math, plus CUDA *.cu.cc GPU variants.
• Ops (tensorflow/core/ops/) — OpDef registrations and shape inference functions.
• Graph (tensorflow/core/graph/) — graph construction, partitioning, edge bookkeeping.
• Grappler (tensorflow/core/grappler/) — graph-level optimizer (constant folding, layout, arithmetic, memory).
• TFRT (tensorflow/core/tfrt/) — newer asynchronous runtime fallback.

See systems/core-runtime, systems/kernels-and-ops, systems/distributed-runtime.

Compiler stack (tensorflow/compiler/)

• tf2xla/ — converts a TF subgraph into an XLA HLO computation.
• jit/ — XlaCompile/XlaRun ops and the auto-clustering pass that decides which subgraphs to JIT.
• aot/ — tfcompile ahead-of-time compilation (used to ship models as static libs).
• mlir/ — MLIR dialects and passes for TF, TFLite, TF-Quant, StableHLO, etc. (see tensorflow/compiler/mlir/).
• tf2tensorrt/ — integration with NVIDIA TensorRT.

The XLA core itself lives in a separate openxla/xla repo and is pulled in via third_party/xla. See compilers/xla, compilers/mlir.

TensorFlow Lite (tensorflow/lite/)

A self-contained interpreter for mobile/embedded inference. Reads a flatbuffer model (schema/schema.fbs), runs op kernels written for size, and supports delegation (GPU, NNAPI, XNNPACK, CoreML, Hexagon). Has its own converter (tensorflow/lite/python/, tensorflow/lite/toco/), micro runtime, iOS/Android/Swift/ObjC bindings.

See apps/tensorflow-lite.

Tooling and build

• Bazel is the build system. Top-level WORKSPACE, MODULE.bazel, and the tensorflow.bzl macros define how everything compiles.
• ./configure (configure.py) is a Python wizard that writes .tf_configure.bazelrc with CUDA/ROCm/MPI/Python paths.
• CI lives in .github/workflows/ (GitHub Actions) and ci/ (the larger Kokoro-driven pipelines and Docker images).

See how-to-contribute/tooling.

End-to-end execution example

A user calls tf.add(a, b) in eager mode:

1. The Python tf.add is generated from OpDefs and lives in tensorflow/python/ops/ (specifically gen_math_ops.py, generated from tensorflow/core/ops/math_ops.cc).
2. It calls into the eager runtime via pywrap_tfe.cc and tensorflow/python/eager/.
3. The eager runtime (tensorflow/core/common_runtime/eager/) looks up the kernel for the device, allocates outputs, runs the kernel.
4. The Add kernel lives in tensorflow/core/kernels/cwise_op_add_*.cc and dispatches to an Eigen functor (CPU) or a CUDA kernel (GPU).

A user calls a @tf.function-decorated function:

1. The Python function is traced once — every TF op call records an Operation into a FuncGraph.
2. The captured graph is registered with the eager FunctionLibraryRuntime.
3. On call, the runtime may run Grappler optimizations, partition the graph across devices, and execute it via the executor in tensorflow/core/common_runtime/executor.cc.
4. If jit_compile=True, the subgraph is handed to tf2xla, lowered to HLO, then compiled by XLA into device-specific code.

See features/tf-function-and-autograph.

Cross-cutting concerns

• Resource model — Variable, Iterator, Hashtable, etc. are Resources managed by ResourceMgr (tensorflow/core/framework/resource_mgr.h). They live across op invocations.
• Allocator hierarchy — every device has one or more Allocators; GPU has BFC allocator, host has process state allocators. See tensorflow/core/framework/allocator.h.
• Rendezvous — cross-device tensor exchange uses Rendezvous/RemoteRendezvous keyed by (src,dst,frame_id,...).
• Protobufs — most cross-process and on-disk formats are protos under tensorflow/core/protobuf/ and tensorflow/core/framework/*.proto.

Reading this wiki

The TOC follows TensorFlow's own vocabulary:

• apps — language frontends + TFLite (the user-facing surfaces).
• systems — internal runtime components.
• compilers — XLA, MLIR, TensorRT, AOT.
• features — cross-cutting capabilities (tf.data, tf.distribute, AutoGraph, SavedModel, profiler).
• reference — config flags, key types, dependency list.