---
name: astrology-systems-design
description: 'Use when designing applied astrology software systems for Alex: mobile ephemeris/time-wave visualizations, transit UIs, astrology-informed trading research, blind backtesting, Moon-degree matrices, and app/product workflows that combine symbolic rules with executable data pipelines.'
version: 1.0.0
author: Hermes Agent + Alex
license: MIT
metadata:
  hermes:
    tags: [astrology, systems, timewave, data-viz, trading, backtesting, ephemeris, moon-timing]
    related_skills: [astral-chart-api, astral-transit-calendar, astrology-mobile-data-viz, astrology-trading-research]
---

# Astrology Systems Design

## Overview

Use this umbrella skill for applied astrology systems: interfaces, research loops, temporal visualizations, and data-driven products where astrological timing must be computed, rendered, tested, or operationalized.

The absorbed skills are preserved under `references/absorbed/` for full detail. This SKILL.md keeps the class-level decision rules and points to the right subsection.

## When to Use

- Building or debugging Time Wave, transit calendar, ephemeris, lunation, or mobile astrology UI.
- Designing SVG/canvas/React visualizations for dense temporal transit data.
- Building astrology-informed trading research systems, Moon-degree matrices, planetary-hour tests, paper trading, or blind backtests.
- Creating executable Hermes cron/research loops that combine ephemeris schedules with external outcome data.

## Subsection: Mobile Astrology Data Visualization

Canonical pattern: **portrait phone-first time waves**. Time runs top → bottom; each transit rises from a baseline, peaks at exactitude, and falls back. Planet hue identifies the body; amplitude is aspect-type based, not planet based. Use dark celestial restraint, editorial typography, and glyphs rendered as real text/webfont/path glyphs — not emoji screenshots.

Important defaults:

- iPhone-style `390 × 844` portrait viewBox unless a scrollable variant is needed.
- Dark midnight navy, subtle hardcoded stars, one accent at a time.
- Per-planet color system from the absorbed reference.
- Long/retrograde aspects need signed speed, bounded duration, validation of suspicious `exactAt`, and stable scroll buffers.
- Ephemeris + Wave mode shares one scrollable time coordinate system; fixed cursor/readout does not mean fake local incrementing.

Full preserved detail: `references/absorbed/astrology-mobile-data-viz/SKILL.md` and its reference files.

## Subsection: Astrology Trading Research

Default posture: research/simulation, not financial advice or live trading permission. Evaluate astrological ideas by frequency, sample size, blind schedule sealing, benchmark comparison, and same-frequency random baselines.

Signal roles:

1. **Regime filter** — slow context and risk limits.
2. **Setup window** — medium-frequency tradable windows.
3. **Execution trigger** — high-frequency timing such as Moon aspects, Moon degrees, or planetary hours.
4. **Allocation filter** — size/token/cash exposure modifier.

Important defaults:

- Moon-heavy execution is the first serious crypto timing layer.
- Test 360 Moon-degree matrices deliberately; do not hype a single raw winner.
- Use 1h/15m/5m candles when trigger precision requires it; daily candles are too blunt for exact lunar triggers.
- Seal astrology-only schedules before fetching/inspecting market outcomes.
- Rank by evidence, robustness, and sample count — not just alpha.

Full preserved detail: `references/absorbed/astrology-trading-research/SKILL.md` and its reference files.

## Subsection: Sky Compass / Planet Finder

For mobile apps that let users physically point an iPhone toward planets, use **local horizontal coordinates**: planet azimuth + altitude for the observer's current lat/lon/time. Never map zodiac longitude directly to north/east/south/west. The canonical pattern is: Astro Engine computes sky coordinates, Astral Hermes proxies `/api/sky/now`, and the frontend compares device heading to planet azimuth.

Implementation defaults:

- MVP is **azimuth-first**: reliable left/right/aligned compass guidance before AR-style pitch/altitude instructions.
- iOS Safari needs `DeviceOrientationEvent.requestPermission()` from a user gesture.
- Request location + orientation explicitly; prefer `webkitCompassHeading`, fallback to `360 - alpha`.
- Return/render below-horizon state separately from azimuth alignment.
- Resolve ephemeris body names to internal body IDs before filtering, or body arrays may silently come back empty.

Full session-derived detail: `references/sky-compass-planet-finder.md`.

## Subsection: Astral Hermes Product UX / Chat-First Architecture

When designing Astral Hermes as a user-facing app, default to **chat as the home surface**. The product should feel like a living astrologer/guide that operates the machinery for the user, not a dashboard where users must understand onboarding forms, sidebar context pills, chart tools, and slow backend tool calls. First-run birth data capture should happen conversationally in chat with a prominent inline mic and structured confirmation card; forms are fallback/edit surfaces. Sidebar knowledge should be a Memory Library with explicit “Working with…” context cards/thread-scoped context, not only ambiguous top pills.

For current Astral Hermes architecture, preserve this product rule: **Hermes is always the user-facing responder**. Do not add or preserve `web backend -> direct model provider -> assistant answer` shortcuts for chat just to make UX feel fast. Instead, use Hermes run profiles that combine model tier (`fast`/`balanced`/`deep`), skill/tool budget, cached KB/chart context, and foreground/background response contracts. Simple facts can use fast Hermes + compact chart context; full chart/transit/relationship readings should acknowledge immediately, show progress/status/animation, and finish via background Hermes jobs that save readings to KB/sidebar. Benchmark tenant Hermes latency by profile before making speed claims. See `references/astral-responsive-hermes-architecture.md` and `references/astral-chat-first-product-architecture.md`.

**Current architecture rule:** user-facing chat answers should come from tenant Hermes, not direct web-backend provider/model calls. Fast UX should be achieved through Hermes run profiles: model tier (`fast`/`balanced`/`deep`), skill/tool budget, cached chart/KB context, and foreground/background behavior. Do not discuss “fast vs deep Hermes” without factoring provider/model selection. If tenant Hermes is too slow when invoked synchronously, benchmark and optimize/persist/background Hermes rather than restoring direct model-answer bypasses. See `references/astral-responsive-hermes-run-profiles.md`.

Older chat-first details remain in `references/astral-chat-first-product-architecture.md`.

## Subsection: Astral Hermes Product Flow

For Astral Hermes app/product work, default to **chat as the home** and let Hermes operate the machinery. New users should land in chat, receive a conversational birth-data intake prompt with an inline mic, confirm parsed birth data in-chat, then continue while chart/bootstrap work runs in the background. Sidebar knowledge should behave like a memory library with explicit context cards / “Working with…” state rather than mysterious tiny pills. See `references/astral-chat-first-product-flow.md` for the session-derived UX and implementation pattern.

## Subsection: Astral Chart Storytelling / Canvas Focus

For Astral Hermes guided chart visuals (rulership-chain stories, dignity walkthroughs, aspect explanations, transit-to-natal stories), prefer integrating focus state into the actual `AstroChartCanvas` renderer instead of stacking a separate overlay canvas. Use renderer-level opacity/dimming so non-focused planets, signs, houses, and aspects fade while focused bodies/sign sectors/arrows remain full strength. Keep the story API generic (`setStoryFocus({ bodies, signs, edge, pulse, progress, dimAlpha })`) and keep the sequence/caption logic outside the renderer. For rulership stories, arrows communicate rulership authority, so draw **ruling planet → ruled planet** (e.g. Mars → Saturn for Saturn in Scorpio), animate arrow growth tail-to-head, and trim endpoints so glyphs/halos do not obscure the arrow. See `references/astral-chart-storytelling-canvas.md` for the session-derived implementation pattern and pitfalls.

## Subsection: Astral Chart Storytelling Labs

When prototyping visual chart explanations, start with a standalone hidden lab route and fixed/sample natal chart before wiring into saved tenant birth data or background reading runs. Reuse Astral's SVG-derived `AstroChartCanvas` in fixed natal mode, add a generic overlay/story layer for highlights/arrows/captions, and keep fast topology extraction deterministic and separate from LLM reading composition. For rulership-chain stories, use traditional rulers only and generate a storyboard from Sun/Moon/Asc/MC chains. See `references/astral-chart-storytelling-lab.md`.

## Subsection: Astral Hermes Chart Story / Waiting-State Visuals

For fast “while the full reading is cooking” experiences, use deterministic chart-derived topology plus the existing Astral canvas chart renderer. The current Astral chart wheel is canvas, but it is a faithful port of the old SVG renderer: 200-unit virtual geometry, Path2D arcs, astro-font glyph codes, chartstyle transcription, DPR-aware resizing, and ResizeObserver redraws. Do not replace it with raw SVG just to get highlighting. Add generic `AstroChartCanvas` overlay/camera primitives, then feed them from a fast traditional rulership-chain topology object. Prototype hidden lab routes such as `/lab/rulership-chain` or `/chart/story` before wiring into chat onboarding. See `references/astral-rulership-chain-chart-story.md`.

## Subsection: Astral Hermes Go-to-Market Launch Spine

When Alex asks where Astral Hermes is relative to market launch, or what to build next after chat/chart/HD/time-wave infrastructure exists, prioritize a **single launch spine** over more deep features: one public offer, one first-user funnel, one campaign, and one analytics loop. The recommended wedge is a free personalized current-sky reading from the user's real birth chart. For first-time users, keep the UI constrained to birth-data intake and first reading; defer full Knowledge/Threads/Views complexity until after activation. See `references/astral-go-to-market-launch-spine.md` for the session-derived funnel, first-reading artifact shape, analytics events, and Creative/Social/Ads flywheel.

## Subsection: Astro Engine Search Architecture

For Alex's astrology search/backtesting/search-corpus ideas, default to a separated architecture: **Astro Engine** owns astrology calculation/search, **Astral Hermes** is the astrology-facing interface, and **HD Prism** remains the Human Design/bodygraph app. HD Prism saved charts can be imported as a compact test corpus, but do not turn HD Prism itself into the astrology search engine unless Alex explicitly asks for product unification.

Build search in two layers:

1. **Ephemeral time search** — scan/refine date ranges for placements, aspects, multi-body clusters, and exactitudes without persistent chart data.
2. **Local chart corpus search** — store compact normalized placements/aspects from imported charts in Astro Engine-side SQLite/indexes, not giant duplicated HD Prism JSON blobs.

Use a Hermes skill/API wrapper as the first interface so Astral Hermes can run natural-language searches before a UI exists. Start with a thin vertical slice: schema + normalized placement/aspect derivation + one-chart indexing CLI + 25-chart HD Prism sample import + corpus search endpoint, then build the harder century-scale ephemeral time search. Full session-derived detail and roadmap pointer: `references/astro-engine-search-architecture.md
- `references/astro-engine-search-vertical-slice.md` — implementation notes for the first Astro Engine SQLite corpus/search/API vertical slice, including HD Prism import and Program config mutation pitfall.`.

## Shared Verification Checklist

- [ ] Ephemeris/timezone/source-of-truth calculations are explicit.
- [ ] UI render behavior is tested at mobile portrait widths.
- [ ] Dense event sets are capped/ranked without hiding valid long-running events.
- [ ] Research schedules are sealed before outcome reveal.
- [ ] Metrics show sample count, benchmark, granularity, and robustness.
- [ ] Interpretive text stays sober and traditional-Alex aligned.

## Common Pitfalls

- Treating rare outer-planet events as live systems without enough samples.
- Making Time Wave amplitude planet-dependent after Alex corrected it to aspect-tier dependent.
- Faking ephemeris/ruler labels instead of deriving them from real longitude/time samples.
- Using daily candles for exact lunar/aspect triggers.
- Letting UI polish hide unverified math, or letting statistical output become hypey symbolic narration.