A powerful relational database and automation engine for Human Design analysis. This project maps raw astronomical coordinates from specialized APIs to a deep internal database of Human Design definitions, generating comprehensive, multi-layered reports for developers and wellness practitioners.
Instead of just calculating planetary positions, hddata_api provides the semantic layer—explaining the meaning, biology, and mechanics behind every activation in a Human Design chart.
Variables or only Centers) via CLI flags or API parameters.run_hd.js) and Fastify-powered Web API for seamless integration.This API provides a deep knowledge base for the following HD mechanics:
The project includes a built-in Fastify-powered API for programmatic access to Human Design analysis.
/docs.Start the API Server:
node src/server.js
By default, the server runs on http://localhost:3000.
Access Interactive Docs: Open http://localhost:3000/docs in your browser to view the Swagger UI and test endpoints directly.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Check API and Database connectivity. |
/calculate-report | GET | Generate HD reports (JSON or Markdown). |
Example Request:
GET /calculate-report?year=1990&month=5&day=15&hour=10&minute=30&place=London&json=true§ions=Type,Authority
better-sqlite3)192.168.100.200:5434 but is configurable via .env).hd.3362173.xyz).HDDATA_API_TOKEN to secure your self-hosted API.Clone the repository:
git clone <repository-url>
cd hddata_api
Install dependencies:
npm install
Configure Environment:
Create a .env file in the root directory. You can use any provided example file as a template.
# Database Configuration
DB_TYPE=postgres # Options: 'postgres' or 'sqlite'
DB_HOST=192.168.100.200
DB_PORT=5434
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=hdesign
DB_SQLITE_PATH=./hd_data.sqlite # Optional, defaults to ./hd_data.sqlite
# API Configuration
HD_API_URL=https://hd.3362173.xyz/...
HD_API_TOKEN=your_external_api_token
# Security (New in v0.5.0)
HDDATA_API_TOKEN=your_internal_secret_token
For PostgreSQL:
Run the schema creation script in your DB client (e.g., db/tablecreation.sql) and then populate data using node scripts/import_data.js (if available).
For SQLite:
The application supports migration or initial setup. Check scripts/migrate_pg_to_sqlite.js if you are moving from Postgres.
You can run the API using Docker and Docker Compose. This ensures a consistent environment and easy persistence management.
Configure Environment: Ensure your .env file is set up (see .env.example or documentation).
Build and Run:
docker-compose up -d --build
The API will be available at http://localhost:3000 (or API_PORT defined in .env: defaults to 9022 if using the provided config).
Persistence: The SQLite database is persisted in ./hd_data.sqlite on your host machine.
Stop:
docker-compose down
The main entry point is src/run_hd.js.
To generate a Human Design report for a specific birth event:
node src/run_hd.js <year> <month> <day> <hour> <minute> "<place>" [options]
Parameters:
year, month, day: Birth date (e.g., 1985 10 25)hour, minute: Birth time in 24h format (e.g., 14 30)place: City and Country (e.g., "New York, USA")Options:
--simple: Generate a simplified report using simple schema logic.--json: Generate a structured JSON file instead of a Markdown report.--sections=<list>: Filter report elements by providing a comma-separated list of sections. Possible values: General, Definition, Type, Authority, Profile, Centers, Channels, Variables, Activations, Bases, Tones, Colors.node src/run_hd.js 1985 10 25 14 30 "New York, USA" --json
This will generate a file named response_New_York,_USA_1985.json in the current directory.
You can generate highly targeted reports by specifying sections:
node src/run_hd.js 1985 10 25 14 30 "New York, USA" --sections=General,Centers
Or include advanced mechanics in a JSON output:
node src/run_hd.js 1985 10 25 14 30 "New York, USA" --json --sections=Activations,Bases,Tones
Run the test suite using Jest.
npm test
npm run test:pg # Force Postgres
npm run test:sqlite # Force SQLite
docs/openapi.yaml for API details if you are interacting with the backend service directly.CHANGELOG.md for version history.Contributions are welcome! Please ensure you:
[License Type] - See LICENSE file for details.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
public_centers, 11x duplicates in public_circuits, and 18x duplicates in simple_circuits from both PostgreSQL and SQLite databases.PRIMARY KEY and UNIQUE(name) constraints to these tables in both database engines to prevent future duplication./v2/calculate with full upstream parity.include/exclude dot-notation filtering by forwarding parameters to the upstream Hologenetic API./v2/calculate-report.V2Enrichment to provide deep database mapping for V2 responses, including Type, Authority, Profile, and Variable descriptions.include/exclude logic in V2 routes, allowing granular control over report sections.V2Markdown to be fully conditional, ensuring it can generate reports for any combination of requested sections without crashing.variables were only included if the general section was requested. Variable data is now accessible at the top level and correctly enriched.HDDATA_API_TOKEN.auth middleware supporting X-API-Tokens header and Authorization: Bearer.HDDATA_API_TOKEN to environment configuration and Docker Compose.ValidationService to support standard authority names (e.g., "Sacral Authority", "Emotional Authority") returned by external APIs./health endpoint examples and resolved servers configuration issue that pointed Swagger functionality to localhost.run_hd.js.src/server.js) compliant with OpenAPI 3.0.GET /calculate-report with full parity to the CLI, supporting JSON/Markdown output and selective sections.GET /health for monitoring service and database connectivity./docs.tests/api/) for all new endpoints.--sections CLI flag allowing users to include only specific parts of the report (e.g., General, Centers, Activations).tests/cli_selective.test.js to verify filtering logic across all output formats.general section to basic metadata, removing duplicated fields (variables, centers, etc.) that have their own top-level sections.--json flag to src/run_hd.js to generate reports in a structured JSON format, facilitating future API integrations.tests/cli_json.test.js and tests/parity/json_structure.test.js to ensure the correctness of JSON output and CLI flag behavior..md or .json file based on the provided flags.prepareChartData function.prevalence_percent, population_percent) as numeric values across all database drivers.ValidationService to enforce strict Human Design rules (Gates, Lines, Colors, Tones, Bases, etc.) at runtime.id="hd-general") for easier programmatic parsing and testing.src/run_hd.js. The system now rejects invalid astronomical data with descriptive HD Logic Violation errors.README.md to accurately reflect the project features, updated tech stack (SQLite support), and included comprehensive usage instructions.gh CLI for automated GitHub Release creation with attached release notes.release.md SOP to include explicit steps for documentation updates and GitHub Release drafting.DBService to support both PostgreSQL and SQLite.scripts/migrate_pg_to_sqlite.js to migrate data from Postgres to SQLite.data/hddata/types.json.jest dependencies.npm test).config, db_connection, schema, data, app, and report test suites.fetchChartData and generateReport.src/run_hd.js and src/generate_report.js to export functions for testing while maintaining CLI usability._willdeleted directory and obsolete scripts (import_*, inspect_*).jest to devDependencies.run_hd.js to properly handle 'Generator' type in the public schema without incorrect mapping.src, tests, db, scripts, data) for better maintainability.tests/ directory.release.md) with visual workflows and automated steps.package.json with metadata and test scripts.Content type
Image
Digest
sha256:4eaca75cb…
Size
71.8 MB
Last updated
4 months ago
docker pull dturkuler/hddata_api