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

# Backend API

> Apollo GraphQL Federation API on AWS Lambda with Neo4j, Cognito auth, and supporting services.

## Overview

The Brighthive backend is a GraphQL API built with Apollo Federation v2, deployed on AWS Lambda behind API Gateway. It serves as the central coordination layer between the webapp, BrightAgent, and all customer infrastructure.

## Architecture

<CardGroup cols={2}>
  <Card title="GraphQL API" icon="code">
    Apollo Federation v2 running on Lambda + API Gateway. Provides a unified query interface for all platform operations at `api.{env}.brighthive.net`.
  </Card>

  <Card title="Neo4j (SSOT)" icon="share-nodes">
    Graph database on EC2 storing all metadata, lineage, user/workspace/org relationships, and data asset catalog. The single source of truth for the entire platform.
  </Card>

  <Card title="Cognito Auth" icon="lock">
    Two user pools — Platform (customer users) and Internal (admin). JWT tokens authenticate all API requests via API Gateway custom authorizers.
  </Card>

  <Card title="DynamoDB" icon="database">
    Stores account mappings (`S3BucketsByAccount`) and data asset references (`TableIdsByDataAssetUuid`) for fast lookups.
  </Card>
</CardGroup>

## Key Responsibilities

* **Authentication & Authorization** — Cognito JWT validation, workspace-scoped access control.
* **Data Catalog Operations** — CRUD operations on data assets, schemas, and metadata in Neo4j.
* **Workspace Coordination** — Routes queries to the correct workspace's Redshift API based on Neo4j metadata.
* **User Management** — User creation, workspace membership, role assignment.
* **Ingestion Orchestration** — Coordinates file uploads, Airbyte connections, and data onboarding workflows.
* **Service Integration** — Connects to OpenMetadata, Stream.io, Redis, and customer infrastructure.

## Supporting Services

* **Redis** — Caching layer for frequently accessed metadata and API responses.
* **OpenMetadata** — Unified metadata catalog integration via the Internal API stack.
* **Stream.io** — Powers real-time collaboration and chat within the webapp.
* **S3 + CloudFront** — Static asset hosting and delivery.

## API Endpoints

* `api.{env}.brighthive.net` — Main GraphQL API (Apollo Federation).
* `api.{env}.brighthive.net/ogm` — Neo4j Object-Graph Mapping endpoint.

## How Queries Flow

```
User (webapp) → API Gateway → Cognito Authorizer → GraphQL Lambda → Neo4j (metadata) → Workspace Redshift API → Results
```

The GraphQL Lambda looks up workspace metadata in Neo4j (account ID, Redshift API URL), then calls the workspace's Redshift REST API to execute the query. Results flow back through the same path.