Health Auto Export Server

A server application for ingesting and retrieving health data.

Upstream Lineage

This repo is a rewrite-oriented descendant of the original project by the Health Auto Export app producer:

• Original upstream: HealthyApps/health-auto-export-server
• This repo: nilswx/health-auto-export-server

It is not a shallow fork. The current architecture here is intentionally PostgreSQL + Hasura + Fastify/TypeScript, with custom proxy/OpenAPI behavior.

Key Features

• PostgreSQL database for structured health data storage
• Hasura GraphQL Engine for advanced querying capabilities
• Hasura REST API for direct REST API access
• Fastify for fast and low overhead web server
• TypeScript for type safety and better development experience
• Docker for containerization and easy deployment

Available APIs

• Application Server API - Custom endpoints (available on port 3001 by default)
• Hasura GraphQL API - Proxied through the application server at /graphql
• Hasura REST API - Proxied through the application server at /api/
• OpenAPI Documentation - Available at /openapi.yaml

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js 16+ (for local development)

Quick Start

1. Clone the repository
2. Start the development environment:

# Start in development mode with Hasura
npm run dev:all

# Or start individual services
npm run docker:up    # Start PostgreSQL and Hasura
npm run dev          # Start the Node.js server in dev mode

Auth note

In production deployments, ingestion and read APIs should be protected with an API_KEY secret and clients should send either:

• api-key: <API_KEY>
• Authorization: Bearer <API_KEY>

For the iOS Health Auto Export app integration, set the header name to api-key.

Hasura API

Hasura provides both GraphQL and REST APIs for your data:

GraphQL

Access the GraphQL API directly at:

http://localhost:8080/v1/graphql

Or through the application server proxy at:

http://localhost:3001/graphql

REST API

Automatically generated REST APIs are available through the application server proxy:

http://localhost:3001/api/{table_name}
http://localhost:3001/api/{table_name}/{id}

OpenAPI Documentation

The application automatically generates OpenAPI documentation for all available REST endpoints:

http://localhost:3001/openapi.yaml

This can be viewed with tools like Swagger UI or Redoc.

Architecture

This system uses a layered architecture:

• PostgreSQL for data storage
• Hasura for GraphQL and REST API generation
• Application server for custom endpoints and proxying

Data Flow

1. Health data is ingested via the /api/data endpoint
2. Data is parsed and stored in the appropriate PostgreSQL tables
3. When new tables are created, Hasura is automatically signaled to reload its schema definitions and create REST APIs
4. Data can be retrieved via the proxied GraphQL API or REST API endpoints

Development

Project Structure

• src/ - Source code for the application server
  • controllers/ - Request handlers
  • db/ - Database connection and schema management
  • models/ - Data models and types
  • plugins/ - Fastify plugins
  • routes/ - API routes
  • utils/ - Utility functions
• hasura/ - Hasura configuration
• scripts/ - Helper scripts

API Endpoints

Application Server

• POST /api/data - Main ingestion endpoint for health data
• GET /api/metrics/:selected_metric - Retrieve data for a specific metric
• GET /api/workouts - List all workouts
• GET /api/workouts/:id - Get details for a specific workout
• POST /admin/reload-services - Manually trigger service reloads for Hasura
• GET /openapi.yaml - Get the OpenAPI specification for all available APIs

Proxied APIs

• POST /graphql - GraphQL API proxy to Hasura
• GET/POST /api/* - REST API proxy to Hasura

Adding New Features

To add new functionality:

1. Create new controllers and routes in the appropriate directories
2. Update the database schema if needed
3. Register new routes in src/index.ts

References

• Fastify Documentation
• Hasura Documentation
• PostgreSQL Documentation

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.