# twitter/twitter-server architecture

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

- Interactive diagram: https://gitdiagram.com/twitter/twitter-server
- Repository: https://github.com/twitter/twitter-server

## Overview

##### Project type and purpose
- TwitterServer is an open-source server template / framework (not a standalone full-stack app). It provides core server components—administrative HTTP server, lifecycle management, tracing, stats, logging integrations—for building production-grade Scala services at Twitter and beyond.
- Key indicators:
- Multi-module library (server, logback-classic, slf4j-jdk14, slf4j-log4j12, opencensus)
- README describes “template from which servers…are built” and “common application components.”

##### File structure
- Top-level modules:
- server/ – the core template and HTTP admin server
- logback-classic/, slf4j-jdk14/, slf4j-log4j12/ – pluggable logging handlers
- opencensus/ – tracing and metrics via OpenCensus
- Supporting directories:
- doc/ – Sphinx-based user guide and examples
- project/, build.sbt, BUILD.bazel, sbt, BUILD.bazel – build and CI configuration
- .github/ – CI workflows and PR templates
- Each module follows standard Maven/Bazel structure (src/main/scala, src/main/resources, src/test).

##### README for additional insights
- Mentions administrative HTTP server, tracing, stats, and wiring for production use.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core flow
    CONFIG["CONFIG.ini"]:::config -->|loads flags| FlagResolver["FlagResolver"]:::config
    click CONFIG "https://github.com/twitter/twitter-server/blob/develop/CONFIG.ini"
    click FlagResolver "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/FlagResolver.scala"

    FlagResolver -->|resolves| CoreServer["Core Server Module"]:::core
    click CoreServer "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/TwitterServer.scala"

    subgraph "Core Server Components"
        style CoreServer fill:#f9f,stroke:#333,stroke-width:2px
        AdminHttpServer["Admin HTTP Server"]:::core
        click AdminHttpServer "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/AdminHttpServer.scala"

        Lifecycle["Lifecycle & Hooks"]:::core
        click Lifecycle "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/Lifecycle.scala"
        Hook1["Hook"]:::core
        click Hook1 "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/Hook.scala"
        Hook2["NewHook"]:::core
        click Hook2 "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/NewHook.scala"
        Hooks["Hooks"]:::core
        click Hooks "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/Hooks.scala"

        Stats["Stats & Metrics Collector"]:::core
        click Stats "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/Stats.scala"

        Resolver["Service Resolver/Announcer"]:::core
        click Resolver "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/resolver/FlagAnnouncer.scala"

        subgraph HandlersAndFilters
            HandlerGroup["HTTP Handlers (plugin points)"]:::core
            click HandlerGroup "https://github.com/twitter/twitter-server/tree/develop/server/src/main/scala/com/twitter/server/handler/"
            Filters["Admin HTTP Filters"]:::core
            click Filters "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/filters/AdminThreadPoolFilter.scala"
            Views["MVC-style Views"]:::core
            click Views "https://github.com/twitter/twitter-server/tree/develop/server/src/main/scala/com/twitter/server/view/"
            Lint["Lint Rules"]:::core
            click Lint "https://github.com/twitter/twitter-server/tree/develop/server/src/main/scala/com/twitter/server/lint/"
        end

        Utils["Utility Libraries"]:::core
        click Utils "https://github.com/twitter/twitter-server/tree/develop/server/src/main/scala/com/twitter/server/util/"
    end

    CoreServer -->|starts| AdminHttpServer
    CoreServer -->|registers hooks| Lifecycle
    CoreServer -->|registers stats| Stats
    CoreServer -->|uses resolver| Resolver
    CoreServer -->|loads handlers| HandlerGroup
    CoreServer -->|loads filters| Filters
    CoreServer -->|loads views| Views
    CoreServer -->|loads lint rules| Lint
    CoreServer -->|uses util| Utils

    AdminHttpServer -->|routes requests to| HandlerGroup
    AdminHttpServer -->|applies| Filters
    AdminHttpServer -->|renders| Views

    %% Logging subsystem
    subgraph "Logging (SLF4J)" 
        style Logging fill:#bbf,stroke:#333,stroke-width:2px
        SLF4J["SLF4J API"]:::logging
        click SLF4J "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/handler/LoggingHandler.scala"
        NoSLF["NoLoggingHandler"]:::logging
        click NoSLF "https://github.com/twitter/twitter-server/blob/develop/server/src/main/scala/com/twitter/server/handler/NoLoggingHandler.scala"
        subgraph "Adapters"
            Logback["logback-classic Adapter"]:::logging
            click Logback "https://github.com/twitter/twitter-server/blob/develop/logback-classic/src/main/scala/com/twitter/server/handler/logback/classic/LoggingHandler.scala"
            JDK14["slf4j-jdk14 Adapter"]:::logging
            click JDK14 "https://github.com/twitter/twitter-server/blob/develop/slf4j-jdk14/src/main/scala/com/twitter/server/handler/slf4j/jdk14/LoggingHandler.scala"
            Log4j12["slf4j-log4j12 Adapter"]:::logging
            click Log4j12 "https://github.com/twitter/twitter-server/blob/develop/slf4j-log4j12/src/main/scala/com/twitter/server/handler/slf4j/log4j12/LoggingHandler.scala"
        end
    end

    CoreServer -->|logs via| SLF4J
    SLF4J -->|delegates to| Logback
    SLF4J -->|delegates to| JDK14
    SLF4J -->|delegates to| Log4j12
    SLF4J -->|can no-op| NoSLF

    %% Tracing subsystem
    subgraph "Tracing (OpenCensus)" 
        style Tracing fill:#bfb,stroke:#333,stroke-width:2px
        ZPages["ZPages Admin Routes"]:::tracing
        click ZPages "https://github.com/twitter/twitter-server/blob/develop/opencensus/src/main/scala/com/twitter/server/opencensus/ZPagesAdminRoutes.scala"
    end

    CoreServer -->|tracing hooks| ZPages

    %% Build & CI
    subgraph "Build & CI (dashed)" 
        style BuildCI stroke-dasharray: 5 5,fill:#fff,stroke:#333
        Bazel["BUILD.bazel"]:::ci
        click Bazel "https://github.com/twitter/twitter-server/blob/develop/BUILD.bazel"
        SBT["build.sbt & project/"]:::ci
        click SBT "https://github.com/twitter/twitter-server/blob/develop/build.sbt"
        CI["CI Workflows"]:::ci
        click CI "https://github.com/twitter/twitter-server/blob/develop/.github/workflows/continuous-integration.yml"
    end

    CoreServer -.->|built by| Bazel
    CoreServer -.->|built by| SBT
    BuildCI -.-> CoreServer

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#fee,stroke:#c96,stroke-width:1px
    classDef logging fill:#bbf,stroke:#123,stroke-width:1px
    classDef tracing fill:#bfb,stroke:#132,stroke-width:1px
    classDef ci fill:#eef,stroke:#339,stroke-width:1px
    classDef core text-align:left
    classDef logging text-align:left
    classDef tracing text-align:left
    classDef config text-align:left
    classDef ci text-align:left
```
