> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.ard.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Pinpoint system architecture and core components

## Architecture Diagram

```mermaid theme={null}
flowchart TB
  %% External DNS / LB and clients
  C["Clients / Internet"] --> R53["Route53"]
  R53 --> HLB["Hetzner Load Balancer"]
  HLB --> P

  %% Pinpoint nodes
  subgraph P["Pinpoint"]
    direction LR
    P0["server 0"]
    P1["server 1"]
    Pn["server ..."]
    PZ["server N"]
  end

  %% Upstream services
  P --> M["ModMS"]
  P --> G["Geos"]
  P --> RO["Redis (overrides)"]
  P <--> RC["Redis (cache)"]
```

## Core Components

<Tabs>
  <Tab title="Pinpoint API">
    The main HTTP API that powers internal and external consumers.

    **Responsibilities:**

    * Serves hourly, daily, and time-segment forecasts
    * Aggregates data from ModMS and other upstream systems
    * Applies overrides and business logic
  </Tab>

  <Tab title="ModMS">
    Provides the underlying numerical weather model data that Pinpoint consumes.

    **Responsibilities:**

    * Serves model fields and time series to Pinpoint
    * Handles model-specific processing and storage
    * Acts as the single source of truth for model data
  </Tab>

  <Tab title="Redis">
    Used for both caching and overrides.

    **Responsibilities:**

    * Caches responses and intermediate data to reduce latency
    * Stores overrides for specific locations, products, or parameters
    * Helps protect ModMS and backend systems from unnecessary load
  </Tab>

  <Tab title="Geos SOLR">
    Geospatial search and location resolution layer.

    **Responsibilities:**

    * Resolves requests from location identifiers or coordinates
    * Powers search and discovery of locations used by Pinpoint
  </Tab>

  <Tab title="Logging & Observability (Loki + Grafana)">
    Centralized logging and metrics using Promtail, Loki, and Grafana.

    **Responsibilities:**

    * Collects logs from Pinpoint instances using Promtail
    * Stores and indexes logs in Loki
    * Visualizes logs and metrics through Grafana dashboards
  </Tab>
</Tabs>

## Data Flow

<Steps>
  <Step title="Client Request">
    A client (apps, website, Qarar, WeatherWatch, media, etc.) sends a request to the Pinpoint API.
  </Step>

  <Step title="Location Resolution">
    Pinpoint resolves the requested location using Geos SOLR and internal location metadata.
  </Step>

  <Step title="Model Data Fetch">
    Pinpoint queries ModMS for the required model fields and time ranges.
  </Step>

  <Step title="Overrides & Business Logic">
    Redis overrides and business rules are applied on top of the raw model data.
  </Step>

  <Step title="Response Caching">
    The response (or intermediate data) is cached in Redis when applicable.
  </Step>

  <Step title="Response to Client">
    Pinpoint returns a JSON response tailored to the client’s needs (hourly, daily, or time-segment forecasts).
  </Step>
</Steps>

## Related Documentation

* [Pinpoint Overview](/data-ai/pinpoint)
* [Getting started](/data-ai/pinpoint/getting-started)
* [Deployment](/data-ai/pinpoint/deployment)
* [FAQ](/data-ai/pinpoint/faq)