# meta/folly architecture

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

- Interactive diagram: https://gitdiagram.com/meta/folly
- Repository: https://github.com/meta/folly

## Overview

Folly is a performance-oriented C++20 library of largely independent components, not a single application with one end-to-end workflow. A user selects a component for a task—such as storing data, coordinating asynchronous work, or parsing JSON—and uses its API to produce a result. The graph preserves major README capabilities and the sampled pipeline and reviewer-tool relationships. Several README-listed modules are absent from the supplied tree; unsampled implementation details and links are omitted.

Main entry points: [`folly/MPMCPipeline.h`](https://github.com/meta/folly/blob/main/folly/MPMCPipeline.h) (MPMC pipeline), [`folly/agents/critic-iterate/codex-reviewer.py`](https://github.com/meta/folly/blob/main/folly/agents/critic-iterate/codex-reviewer.py) (Codex reviewer), [`folly/container/F14Map.h`](https://github.com/meta/folly/blob/main/folly/container/F14Map.h) (F14 maps and sets), [`folly/container/small_vector.h`](https://github.com/meta/folly/blob/main/folly/container/small_vector.h) (Small vector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Containers and data"]
  node_f14["F14 maps and sets<br/>[F14Map.h]"]
  node_smallvec["Small vector<br/>[small_vector.h]"]
  node_sortedvec["Sorted vector maps"]
  node_concurrentmap["Concurrent hash map"]
  node_hive["Hive container<br/>[Hive.h]"]
  node_json["Dynamic and JSON<br/>[DynamicParser.h]"]
  node_pipeline["MPMC pipeline<br/>[MPMCPipeline.h]"]
  node_pipelinequeues["Pipeline queues"]
end

subgraph group_async["Concurrency and async"]
  node_executors["Executors"]
  node_futures["Futures and promises<br/>[Future.h]"]
  node_coroutines["Coroutine utilities<br/>[Task.h]"]
  node_fibers["Fiber manager<br/>[FiberManager.cpp]"]
  node_channels["Channels<br/>[Channel.h]"]
  node_eventbase["Async I/O event loop<br/>[EventBaseManager.h]"]
  node_timeouts["Timer timeouts"]
  node_sync["Synchronized access<br/>[Synchronized.h]"]
  node_sharedmutex["Shared mutex<br/>[SharedMutex.h]"]
  node_threadlocal["Thread local storage<br/>[ThreadLocal.h]"]
end

subgraph group_utilities["Utilities and diagnostics"]
  node_conv["Conversions<br/>[Conv.h]"]
  node_scopeguard["Scope guard<br/>[ScopeGuard.h]"]
  node_function["Move-only function<br/>[Function.h]"]
  node_symbolizer["Symbolizer<br/>[Symbolizer.h]"]
end

subgraph group_agents["Review agents"]
  node_reviewer["Codex reviewer<br/>[codex-reviewer.py]"]
  node_isolated["Isolated agent<br/>[isolated_agent.py]"]
end

node_user(("C++ library user"))

node_user -->|"uses maps"| node_f14
node_user -->|"uses vectors"| node_smallvec
node_user -->|"uses maps"| node_sortedvec
node_user -->|"uses map"| node_concurrentmap
node_user -->|"parses JSON"| node_json
node_user -->|"processes stages"| node_pipeline
node_pipeline -->|"uses queues"| node_pipelinequeues
node_user -->|"schedules tasks"| node_executors
node_user -->|"composes futures"| node_futures
node_user -->|"runs coroutines"| node_coroutines
node_user -->|"uses event loop"| node_eventbase
node_user -->|"protects data"| node_sync
node_user -->|"uses lock"| node_sharedmutex
node_user -->|"stores thread data"| node_threadlocal
node_user -->|"converts values"| node_conv
node_user -->|"guards scope"| node_scopeguard
node_user -->|"uses callable"| node_function
node_reviewer -->|"runs agent"| node_isolated

click node_f14 "https://github.com/meta/folly/blob/main/folly/container/F14Map.h"
click node_smallvec "https://github.com/meta/folly/blob/main/folly/container/small_vector.h"
click node_sortedvec "https://github.com/meta/folly/blob/main/folly/container/sorted_vector_types.h"
click node_concurrentmap "https://github.com/meta/folly/blob/main/folly/concurrency/ConcurrentHashMap.h"
click node_hive "https://github.com/meta/folly/blob/main/folly/container/Hive.h"
click node_json "https://github.com/meta/folly/blob/main/folly/json/DynamicParser.h"
click node_pipeline "https://github.com/meta/folly/blob/main/folly/MPMCPipeline.h"
click node_pipelinequeues "https://github.com/meta/folly/blob/main/folly/detail/MPMCPipelineDetail.h"
click node_executors "https://github.com/meta/folly/blob/main/folly/executors/ThreadPoolExecutor.cpp"
click node_futures "https://github.com/meta/folly/blob/main/folly/futures/Future.h"
click node_coroutines "https://github.com/meta/folly/blob/main/folly/coro/Task.h"
click node_fibers "https://github.com/meta/folly/blob/main/folly/fibers/FiberManager.cpp"
click node_channels "https://github.com/meta/folly/blob/main/folly/channels/Channel.h"
click node_eventbase "https://github.com/meta/folly/blob/main/folly/io/async/EventBaseManager.h"
click node_timeouts "https://github.com/meta/folly/blob/main/folly/io/async/TimerFDTimeoutManager.cpp"
click node_sync "https://github.com/meta/folly/blob/main/folly/Synchronized.h"
click node_sharedmutex "https://github.com/meta/folly/blob/main/folly/SharedMutex.h"
click node_threadlocal "https://github.com/meta/folly/blob/main/folly/ThreadLocal.h"
click node_conv "https://github.com/meta/folly/blob/main/folly/Conv.h"
click node_scopeguard "https://github.com/meta/folly/blob/main/folly/ScopeGuard.h"
click node_function "https://github.com/meta/folly/blob/main/folly/Function.h"
click node_symbolizer "https://github.com/meta/folly/blob/main/folly/debugging/symbolizer/Symbolizer.h"
click node_reviewer "https://github.com/meta/folly/blob/main/folly/agents/critic-iterate/codex-reviewer.py"
click node_isolated "https://github.com/meta/folly/blob/main/folly/agents/scripts/isolated_agent.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_f14,node_smallvec,node_sortedvec,node_concurrentmap,node_hive,node_json,node_pipeline,node_pipelinequeues,node_user toneBlue
class node_executors,node_futures,node_coroutines,node_fibers,node_channels,node_eventbase,node_timeouts,node_sync,node_sharedmutex,node_threadlocal toneAmber
class node_conv,node_scopeguard,node_function,node_symbolizer toneMint
class node_reviewer,node_isolated toneRose
```

## Components

### Containers and data

- [F14 maps and sets](https://github.com/meta/folly/blob/main/folly/container/F14Map.h): `folly/container/F14Map.h`
- [Small vector](https://github.com/meta/folly/blob/main/folly/container/small_vector.h): `folly/container/small_vector.h`
- [Sorted vector maps](https://github.com/meta/folly/blob/main/folly/container/sorted_vector_types.h): `folly/container/sorted_vector_types.h`
- [Concurrent hash map](https://github.com/meta/folly/blob/main/folly/concurrency/ConcurrentHashMap.h): `folly/concurrency/ConcurrentHashMap.h`
- [Hive container](https://github.com/meta/folly/blob/main/folly/container/Hive.h): `folly/container/Hive.h`
- [Dynamic and JSON](https://github.com/meta/folly/blob/main/folly/json/DynamicParser.h): `folly/json/DynamicParser.h`
- [MPMC pipeline](https://github.com/meta/folly/blob/main/folly/MPMCPipeline.h): `folly/MPMCPipeline.h`
- [Pipeline queues](https://github.com/meta/folly/blob/main/folly/detail/MPMCPipelineDetail.h): `folly/detail/MPMCPipelineDetail.h`

### Concurrency and async

- [Executors](https://github.com/meta/folly/blob/main/folly/executors/ThreadPoolExecutor.cpp): `folly/executors/ThreadPoolExecutor.cpp`
- [Futures and promises](https://github.com/meta/folly/blob/main/folly/futures/Future.h): `folly/futures/Future.h`
- [Coroutine utilities](https://github.com/meta/folly/blob/main/folly/coro/Task.h): `folly/coro/Task.h`
- [Fiber manager](https://github.com/meta/folly/blob/main/folly/fibers/FiberManager.cpp): `folly/fibers/FiberManager.cpp`
- [Channels](https://github.com/meta/folly/blob/main/folly/channels/Channel.h): `folly/channels/Channel.h`
- [Async I/O event loop](https://github.com/meta/folly/blob/main/folly/io/async/EventBaseManager.h): `folly/io/async/EventBaseManager.h`
- [Timer timeouts](https://github.com/meta/folly/blob/main/folly/io/async/TimerFDTimeoutManager.cpp): `folly/io/async/TimerFDTimeoutManager.cpp`
- [Synchronized access](https://github.com/meta/folly/blob/main/folly/Synchronized.h): `folly/Synchronized.h`
- [Shared mutex](https://github.com/meta/folly/blob/main/folly/SharedMutex.h): `folly/SharedMutex.h`
- [Thread local storage](https://github.com/meta/folly/blob/main/folly/ThreadLocal.h): `folly/ThreadLocal.h`

### Utilities and diagnostics

- [Conversions](https://github.com/meta/folly/blob/main/folly/Conv.h): `folly/Conv.h`
- [Scope guard](https://github.com/meta/folly/blob/main/folly/ScopeGuard.h): `folly/ScopeGuard.h`
- [Move-only function](https://github.com/meta/folly/blob/main/folly/Function.h): `folly/Function.h`
- [Symbolizer](https://github.com/meta/folly/blob/main/folly/debugging/symbolizer/Symbolizer.h): `folly/debugging/symbolizer/Symbolizer.h`

### Review agents

- [Codex reviewer](https://github.com/meta/folly/blob/main/folly/agents/critic-iterate/codex-reviewer.py): `folly/agents/critic-iterate/codex-reviewer.py`
- [Isolated agent](https://github.com/meta/folly/blob/main/folly/agents/scripts/isolated_agent.py): `folly/agents/scripts/isolated_agent.py`

### Other components

- **C++ library user**

## Connections

- C++ library user → F14 maps and sets: uses maps
- C++ library user → Small vector: uses vectors
- C++ library user → Sorted vector maps: uses maps
- C++ library user → Concurrent hash map: uses map
- C++ library user → Dynamic and JSON: parses JSON
- C++ library user → MPMC pipeline: processes stages (evidence: `folly/MPMCPipeline.h`)
- MPMC pipeline → Pipeline queues: uses queues (evidence: `folly/detail/MPMCPipelineDetail.h`)
- C++ library user → Executors: schedules tasks
- C++ library user → Futures and promises: composes futures
- C++ library user → Coroutine utilities: runs coroutines
- C++ library user → Async I/O event loop: uses event loop
- C++ library user → Synchronized access: protects data
- C++ library user → Shared mutex: uses lock
- C++ library user → Thread local storage: stores thread data
- C++ library user → Conversions: converts values
- C++ library user → Scope guard: guards scope
- C++ library user → Move-only function: uses callable
- Codex reviewer → Isolated agent: runs agent (evidence: `folly/agents/critic-iterate/codex-reviewer.py`)