# googlecloudplatform/gcs-analytics-core architecture

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

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/gcs-analytics-core
- Repository: https://github.com/googlecloudplatform/gcs-analytics-core

## Overview

GCS Analytics Core is a Java library that sits between analytics frameworks and Google Cloud Storage access layers. Its principal read workflow opens an object through the file-system API, then provides a seekable stream with vectored reads, adaptive access behavior, and optional footer or small-object prefetching. The client layer supplies GCS operations and shared caching; configuration, authentication, and telemetry support those runtime paths. The README documents the high-level flow and capabilities; unsampled implementation details are represented only where the README or source index supports them.

Main entry points: [`client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java`](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java) (GCS File System), [`core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java`](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java) (Input Stream), [`client/src/main/java/com/google/cloud/gcs/analyticscore/client/AnalyticsCacheManager.java`](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/AnalyticsCacheManager.java) (Cache Manager), [`client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java`](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java) (GCS Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Framework Integration"]
  node_fs_adapters["File-System Adapters"]
  node_options["Core Options"]
end

subgraph group_stream["Optimized Read Path"]
  node_input_stream["Input Stream"]
  node_smart_channel["Smart Read Channel"]
  node_vectored_io["Vectored Reads"]
  node_adaptive_read["Adaptive Reads"]
  node_footer_optimizer["Footer Prefetch"]
  node_parquet_parser["Parquet Footer Parser"]
  node_small_optimizer["Small-Object Prefetch"]
end

subgraph group_client["GCS Client"]
  node_filesystem["GCS File System"]
  node_output_stream["Output Stream"]
  node_gcs_client["GCS Client<br/>[GcsClientImpl.java]"]
  node_auth["Authentication"]
end

subgraph group_support["Shared Services"]
  node_cache_manager["Cache Manager"]
  node_cache[("Cache Backends")]
  node_telemetry["Telemetry<br/>[Telemetry.java]"]
end

node_engines(("Analytics Engines"))
node_gcs_sdk["GCS Java SDK"]
node_gcs[("Google Cloud Storage")]

node_engines -->|"uses"| node_fs_adapters
node_fs_adapters -->|"opens reads"| node_filesystem
node_options -->|"configures"| node_filesystem
node_filesystem -->|"opens stream"| node_input_stream
node_filesystem -->|"holds"| node_cache_manager
node_input_stream -->|"uses"| node_smart_channel
node_input_stream -->|"uses"| node_vectored_io
node_input_stream -->|"invokes"| node_footer_optimizer
node_input_stream -->|"invokes"| node_small_optimizer
node_footer_optimizer -.->|"parses footer"| node_parquet_parser
node_footer_optimizer -->|"uses cache"| node_cache_manager
node_small_optimizer -->|"uses cache"| node_cache_manager
node_vectored_io -->|"reads cache"| node_cache_manager
node_input_stream -.->|"adapts reads"| node_adaptive_read
node_filesystem -.->|"delegates operations"| node_gcs_client
node_output_stream -->|"writes through"| node_filesystem
node_filesystem -->|"bypasses writes"| node_gcs_sdk
node_gcs_client -->|"issues requests"| node_gcs_sdk
node_auth -->|"configures transport"| node_gcs_client
node_gcs_sdk -->|"accesses"| node_gcs
node_gcs_client -->|"records operations"| node_telemetry
node_cache_manager -.->|"uses backend"| node_cache

click node_options "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GcsAnalyticsCoreOptions.java"
click node_filesystem "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java"
click node_cache_manager "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/AnalyticsCacheManager.java"
click node_cache "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/common/src/main/java/com/google/cloud/gcs/analyticscore/common/cache/AnalyticsCacheCaffeineImpl.java"
click node_input_stream "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java"
click node_smart_channel "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/channel/SmartReadChannel.java"
click node_vectored_io "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/VectoredSeekableByteChannel.java"
click node_adaptive_read "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/AdaptiveReadStrategy.java"
click node_footer_optimizer "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/optimizer/GcsFooterOptimizer.java"
click node_parquet_parser "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/prefetch/ParquetFooterParser.java"
click node_small_optimizer "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/optimizer/SmallObjectOptimizer.java"
click node_output_stream "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageOutputStream.java"
click node_gcs_client "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java"
click node_auth "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/auth/GcsAuthOptions.java"
click node_telemetry "https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/common/src/main/java/com/google/cloud/gcs/analyticscore/common/telemetry/Telemetry.java"

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_fs_adapters,node_options toneBlue
class node_input_stream,node_smart_channel,node_vectored_io,node_adaptive_read,node_footer_optimizer,node_parquet_parser,node_small_optimizer,node_gcs toneAmber
class node_filesystem,node_output_stream,node_gcs_client,node_auth toneMint
class node_cache_manager,node_cache,node_telemetry toneRose
class node_engines,node_gcs_sdk toneIndigo
```

## Components

### Framework Integration

- **File-System Adapters**
- [Core Options](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GcsAnalyticsCoreOptions.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GcsAnalyticsCoreOptions.java`

### Optimized Read Path

- [Input Stream](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java`
- [Smart Read Channel](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/channel/SmartReadChannel.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/channel/SmartReadChannel.java`
- [Vectored Reads](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/VectoredSeekableByteChannel.java): `client/src/main/java/com/google/cloud/gcs/analyticscore/client/VectoredSeekableByteChannel.java`
- [Adaptive Reads](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/AdaptiveReadStrategy.java): `client/src/main/java/com/google/cloud/gcs/analyticscore/client/AdaptiveReadStrategy.java`
- [Footer Prefetch](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/optimizer/GcsFooterOptimizer.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/optimizer/GcsFooterOptimizer.java`
- [Parquet Footer Parser](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/prefetch/ParquetFooterParser.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/prefetch/ParquetFooterParser.java`
- [Small-Object Prefetch](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/optimizer/SmallObjectOptimizer.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/optimizer/SmallObjectOptimizer.java`

### GCS Client

- [GCS File System](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java): `client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java`
- [Output Stream](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageOutputStream.java): `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageOutputStream.java`
- [GCS Client](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java): `client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java`
- [Authentication](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/auth/GcsAuthOptions.java): `client/src/main/java/com/google/cloud/gcs/analyticscore/client/auth/GcsAuthOptions.java`

### Shared Services

- [Cache Manager](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/client/src/main/java/com/google/cloud/gcs/analyticscore/client/AnalyticsCacheManager.java): `client/src/main/java/com/google/cloud/gcs/analyticscore/client/AnalyticsCacheManager.java`
- [Cache Backends](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/common/src/main/java/com/google/cloud/gcs/analyticscore/common/cache/AnalyticsCacheCaffeineImpl.java): `common/src/main/java/com/google/cloud/gcs/analyticscore/common/cache/AnalyticsCacheCaffeineImpl.java`
- [Telemetry](https://github.com/googlecloudplatform/gcs-analytics-core/blob/main/common/src/main/java/com/google/cloud/gcs/analyticscore/common/telemetry/Telemetry.java): `common/src/main/java/com/google/cloud/gcs/analyticscore/common/telemetry/Telemetry.java`

### Other components

- **Analytics Engines**
- **GCS Java SDK**
- **Google Cloud Storage**

## Connections

- Analytics Engines → File-System Adapters: uses (evidence: `README.md`)
- File-System Adapters → GCS File System: opens reads (evidence: `README.md`)
- Core Options → GCS File System: configures (evidence: `README.md`)
- GCS File System → Input Stream: opens stream (evidence: `README.md`)
- GCS File System → Cache Manager: holds (evidence: `README.md`)
- Input Stream → Smart Read Channel: uses (evidence: `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java`)
- Input Stream → Vectored Reads: uses (evidence: `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java`)
- Input Stream → Footer Prefetch: invokes (evidence: `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java`)
- Input Stream → Small-Object Prefetch: invokes (evidence: `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageInputStream.java`)
- Footer Prefetch → Parquet Footer Parser: parses footer
- Footer Prefetch → Cache Manager: uses cache (evidence: `README.md`)
- Small-Object Prefetch → Cache Manager: uses cache (evidence: `README.md`)
- Vectored Reads → Cache Manager: reads cache (evidence: `README.md`)
- Input Stream → Adaptive Reads: adapts reads
- GCS File System → GCS Client: delegates operations (evidence: `client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsFileSystemImpl.java`)
- Output Stream → GCS File System: writes through (evidence: `core/src/main/java/com/google/cloud/gcs/analyticscore/core/GoogleCloudStorageOutputStream.java`)
- GCS File System → GCS Java SDK: bypasses writes (evidence: `README.md`)
- GCS Client → GCS Java SDK: issues requests (evidence: `client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java`)
- Authentication → GCS Client: configures transport (evidence: `client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java`)
- GCS Java SDK → Google Cloud Storage: accesses (evidence: `README.md`)
- GCS Client → Telemetry: records operations (evidence: `client/src/main/java/com/google/cloud/gcs/analyticscore/client/GcsClientImpl.java`)
- Cache Manager → Cache Backends: uses backend (evidence: `client/src/main/java/com/google/cloud/gcs/analyticscore/client/AnalyticsCacheManager.java`)
