# netflix/atlas architecture

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

- Interactive diagram: https://gitdiagram.com/netflix/atlas
- Repository: https://github.com/netflix/atlas

## Overview

##### Project type and purpose
- This is a multi-module Scala backend project (“Atlas”) for managing dimensional time-series data.
- It provides:
- A core engine (data model, query language, algorithms)
- Libraries for JSON serialization, chart rendering, expression evaluation, event streaming, Postgres integration
- Deployable services (web API, standalone server)
- Framework integrations (Spring, Pekko)
- Benchmarks and testkits

##### High-level architecture
- Client/API Tier
- Service/API Tier
- Core/Library Tier
- Data/External Tier

##### Main components
a. Client/API Tier
- HTTP/REST and WebSocket clients
- (Optional) Spring-based applications
b. Service/API Tier
- atlas-webapi (GraphApi, ExprApi, TagsApi, PublishApi)
- atlas-standalone (embedded WebServer)
- atlas-spring-webapi, atlas-spring-lwcapi, atlas-spring-lwc-events (Spring Boot wrappers)
- atlas-pekko (PekkoHttp server, actors, directives)
c. Core/Library Tier
- atlas-core
– model (Query, Datapoint, TimeSeries)
– algorithm (online, rolling aggregations)
– db interfaces (MemoryDatabase, StaticDatabase)
– index (TagIndex implementations)
- atlas-postgres (PostgresDatabase, PostgresService, TagIndex)
- atlas-json (JsonSupport, parser, serializers)
- atlas-chart (ChartEngine, graphing primitives, palette resources)
- atlas-eval (expression evaluator, streaming flows, grapher)
- atlas-lwc-events (LwcEventClient, DatapointEvent, subscriptions)
- atlas-lwcapi (WebSocketSessionManager, StreamsApi, SubscriptionManager)
d. External/Data Tier
- PostgreSQL database
- (Optional) static files (charts palettes)
- (Optional) external metrics stores or LWC data sources

##### Relationships & data flows
- Clients → atlas-webapi / atlas-standalone (HTTP + WebSocket)
- WebAPI controllers → core engine
- ExprApi → atlas-core.model + atlas-core.algorithm → database (memory or Postgres)
- GraphApi → atlas-eval → atlas-chart → PNG/JSON output
- PublishApi → atlas-core.db (AggregateCollector) → optionally push to event streams
- TagsApi → atlas-core.index → return tag lists
- atlas-lwcapi → manages WebSocket subscriptions, invokes atlas-lwc-events clients under the hood to push DatapointEvents
- atlas-postgres → implements database layer for persistent time-series and tag index
- atlas-json → used by all APIs & libraries to serialize/deserialize payloads

##### Architectural patterns & design principles
- Layered (API → Service → Core → Persistence)
- Modular: each concern (charting, JSON, evaluation, events, persistence) lives in its own artifact
- Dependency injection: Spring modules wire core libraries into a Boot app
- Actor model: atlas-pekko uses Pekko actors for async HTTP, WebSocket handling

##### Final checklist
- [ ] All major modules/services labeled
- [ ] Notes on protocols (HTTP, WebSocket, JSON, JDBC)
- [ ] Detail sub-components where they drive architecture (APIs, engines, storage)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client/API Tier
    subgraph "Client/API Tier"
        HTTPClient["HTTP/REST Client"]:::external
        WSClient["WebSocket Client"]:::external
        SpringApps["(Optional) Spring-based Apps"]:::integration
    end

    %% Service/API Tier
    subgraph "Service/API Tier"
        atlasWebapi["atlas-webapi\n(ExprApi, GraphApi, PublishApi, TagsApi)"]:::service
        atlasStandalone["atlas-standalone\n(Embedded WebServer)"]:::service
        subgraph "Spring Integrations"
            atlasSpringWebapi["atlas-spring-webapi"]:::integration
            atlasSpringLwcapi["atlas-spring-lwcapi"]:::integration
            atlasSpringLwcEvents["atlas-spring-lwc-events"]:::integration
            atlasSpringPekko["atlas-spring-pekko"]:::integration
            atlasSpringEval["atlas-spring-eval"]:::integration
        end
        atlasPekko["atlas-pekko\n(PekkoHttp Server, Actors)"]:::integration
    end

    %% Core/Library Tier
    subgraph "Core/Library Tier"
        atlasCore["atlas-core\n(model, algorithm, db, index)"]:::core
        atlasPostgresLib["atlas-postgres\n(PostgresDatabase, Service, TagIndex)"]:::core
        atlasJson["atlas-json\n(JsonSupport)"]:::core
        atlasChart["atlas-chart\n(ChartEngine)"]:::core
        atlasEval["atlas-eval\n(Evaluator, Streams)"]:::core
        atlasLwcEventsLib["atlas-lwc-events\n(EventClient)"]:::core
        atlasLwcapiLib["atlas-lwcapi\n(WebSocketSessionManager)"]:::core
    end

    %% Data/External Tier
    subgraph "Data/External Tier"
        PostgresDB["PostgreSQL DB"]:::database
        MemoryDB["Memory DB\n(volatile)"]:::database
        StaticFiles["Static Files\n(Charts)"]:::external
        ExternalMetrics["External Metrics Stores"]:::external
    end

    %% Connections
    HTTPClient -->|"HTTP"| atlasWebapi
    WSClient -->|"WebSocket"| atlasWebapi
    HTTPClient -->|"HTTP"| atlasStandalone
    WSClient -->|"WebSocket"| atlasStandalone
    SpringApps -.-> atlasSpringWebapi

    atlasSpringWebapi --> atlasWebapi
    atlasSpringLwcapi --> atlasLwcapiLib
    atlasSpringLwcEvents --> atlasLwcEventsLib
    atlasSpringPekko --> atlasPekko
    atlasSpringEval --> atlasEval

    atlasWebapi -->|"JsonSupport"| atlasJson
    atlasWebapi -->|"calls Core"| atlasCore
    atlasWebapi --> atlasEval
    atlasWebapi --> atlasChart
    atlasWebapi --> atlasLwcapiLib

    atlasStandalone --> atlasWebapi

    atlasPekko --> atlasCore
    atlasPekko --> atlasEval
    atlasPekko --> atlasChart

    atlasCore --> MemoryDB
    atlasCore --> atlasPostgresLib
    atlasPostgresLib --> PostgresDB
    atlasCore --> atlasLwcEventsLib
    atlasLwcapiLib --> atlasLwcEventsLib
    atlasLwcapiLib --> atlasEval
    atlasEval --> atlasChart

    atlasJson -.-> atlasWebapi
    atlasJson -.-> atlasStandalone
    atlasJson -.-> atlasPekko

    PostgresDB -.-> ExternalMetrics
    MemoryDB -.-> ExternalMetrics
    StaticFiles -.-> atlasChart

    %% Click Events
    click atlasCore "https://github.com/netflix/atlas/tree/main/atlas-core/src/main/scala/com/netflix/atlas/core"
    click atlasPostgresLib "https://github.com/netflix/atlas/tree/main/atlas-postgres/src/main/scala/com/netflix/atlas/postgres"
    click atlasJson "https://github.com/netflix/atlas/tree/main/atlas-json/src/main/scala/com/netflix/atlas/json"
    click atlasChart "https://github.com/netflix/atlas/tree/main/atlas-chart/src/main/scala/com/netflix/atlas/chart"
    click atlasEval "https://github.com/netflix/atlas/tree/main/atlas-eval/src/main/scala/com/netflix/atlas/eval"
    click atlasLwcEventsLib "https://github.com/netflix/atlas/tree/main/atlas-lwc-events/src/main/scala/com/netflix/atlas/lwc/events"
    click atlasLwcapiLib "https://github.com/netflix/atlas/tree/main/atlas-lwcapi/src/main/scala/com/netflix/atlas/lwcapi"
    click atlasWebapi "https://github.com/netflix/atlas/tree/main/atlas-webapi/src/main/scala/com/netflix/atlas/webapi"
    click atlasStandalone "https://github.com/netflix/atlas/tree/main/atlas-standalone/src/main/scala/com/netflix/atlas/standalone"
    click atlasPekko "https://github.com/netflix/atlas/tree/main/atlas-pekko/src/main/scala/com/netflix/atlas/pekko"
    click atlasSpringWebapi "https://github.com/netflix/atlas/tree/main/atlas-spring-webapi/src/main/scala/com/netflix/atlas/webapi"
    click atlasSpringLwcapi "https://github.com/netflix/atlas/tree/main/atlas-spring-lwcapi/src/main/scala/com/netflix/atlas/lwcapi"
    click atlasSpringLwcEvents "https://github.com/netflix/atlas/tree/main/atlas-spring-lwc-events/src/main/scala/com/netflix/atlas/lwc/events"
    click atlasSpringPekko "https://github.com/netflix/atlas/tree/main/atlas-spring-pekko/src/main/scala/com/netflix/atlas/pekko"
    click atlasSpringEval "https://github.com/netflix/atlas/tree/main/atlas-spring-eval/src/main/scala/com/netflix/atlas/eval"

    %% Styles
    classDef core fill:#a8d0e6,stroke:#000,stroke-width:1px
    classDef service fill:#98e698,stroke:#000,stroke-width:1px
    classDef database fill:#ffe599,stroke:#000,stroke-width:1px
    classDef external fill:#fce5cd,stroke:#000,stroke-width:1px
    classDef integration fill:#d5a6bd,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
