# Frontis — GraphQL API | Pilotariak

> Frontis is the GraphQL gateway of Pilotariak. It unifies five data domains into a single API — competitions, clubs, results and disciplines.

[Pilotariak](/) 
GraphQL · Open Source · Federation

# Frontis

Pilotariak's GraphQL API — five data domains, one entry point. Built for developers who want to access Basque pelota data.
[View on GitHub](https://github.com/Pilotariak/frontis) [How it works](#architecture) 
Overview

## A unified API for all data 

Frontis federates five independent services into a single GraphQL entry point. Each domain has its own schema and its own deployment cycle.

### echo

API health check and version.

### categories

Competition categories — owns the `Category` entity.

### clubs

Basque pelota clubs — owns the `Club` entity.

### competitions

Championships and tournaments — owns the `Competition` entity.

### results

Match results — owns the `Result` entity.

### specialties

Pelota disciplines — owns the `Specialty` entity.

How it works

## Simple, open, extensible 

Each service manages its own domain. The gateway composes schemas automatically and resolves cross-domain queries.
01 
### Federated schema

Each service exposes its own GraphQL schema and declares the entities it owns. The gateway composes a consistent supergraph without manual configuration.
02 
### Single entry point

Clients send queries to a single `/graphql` endpoint. The gateway resolves fields across services transparently.
03 
### Multi-league

One API instance serves all leagues. A request header selects the active dataset — no per-league deployment.
04 
### Query safety

Built-in limits on query depth, complexity and size protect the API from expensive operations — configurable per environment.

GraphQL Federation

## 
Entities & @key 

Each service declares the types it owns. The gateway automatically resolves fields that span multiple services.

Federated entities
Entity Service Key `Category` categories `id` `Club` clubs `id` `Competition` competitions `id` `Result` results `id` `Specialty` specialties `id` 
Cross-service resolution

```
# Client query:
{ results { clubA { name } } }

# The gateway:
# 1. Fetches Results with clubA { id }
#    → results service
# 2. Sends _entities([{ __typename:"Club", id }])
#    → clubs service
# 3. Merges { name } into the response
```

Open Source · Apache 2.0

## Build it with us

Frontis is open source and welcomes contributions of all kinds — new subgraphs, bug fixes or documentation improvements.
[View on GitHub](https://github.com/Pilotariak/frontis) [← Back to home](/) 
### Fork & run locally

Clone the repo, install dependencies and start the Apollo gateway locally.

### Open an issue

Found a bug or have an idea? GitHub issues are the right place to discuss and track work.

### Submit a pull request

All pull requests are reviewed. Check the contributing guide in the repository for conventions.