# cnwu16/vedic-astro-skills architecture

> Architecture diagram of the GitHub repository cnwu16/vedic-astro-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cnwu16/vedic-astro-skills
- Repository: https://github.com/cnwu16/vedic-astro-skills

## Overview

1. **What this repository is**
   This is not a single application; it is a **multi-skill astrology toolkit** packaged three ways for **Antigravity, Claude Code, and Codex**. The same domain logic is mirrored under `antigravity/skills/`, `claude-code/skills/`, and `codex/skills/`, with Codex also carrying `agents/openai.yaml` descriptors.

2. **Top-level architecture**
   The system is organized around **seven skills**: `vedic-calculator`, `vedic-reader`, `vedic-core`, `vedic-career`, `vedic-love`, `vedic-rectifier`, and `vedic-synastry`. The first is the computational foundation; the others are analysis or correction layers built on its output.

3. **Canonical data boundary**
   The key architectural contract is an intermediate artifact called **`structured_data.md`**. The calculator produces it, the reader can validate it, and all downstream analysis skills consume it. This makes the calculator the authoritative source for chart data.

4. **Input ingestion and routing**
   User input can arrive as:
   - birth details directly,
   - a PDF/screenshot/text chart report,
   - or two people’s charts for synastry.
   
   The **reader** acts as the entry router: it extracts birth data when needed, or passes direct birth information to the calculator. If no usable input is present, it falls back to a guided prompt flow.

5. **vedic-calculator subsystem**
   This is the **local chart computation engine**. It is Python-based and depends on:
   - **Swiss Ephemeris** data (`scripts/ephe/*.se1`)
   - **PyJHora-derived logic** for positions, dashas, divisional charts, ashtakavarga, and bhava calculations
   - a **Shadbala correction layer** in `shadbala_pyjhora.py`
   
   It is designed as **fail-fast** and uses `setup_env.py` to provision and verify the Python environment rather than relying on ad hoc package installation.

6. **vedic-reader subsystem**
   The reader is the **extraction + verification front end**. It supports PDF/image/text-based chart intake, then cross-checks the extracted information against calculator output. The `resources/` directory holds its validation rules and data contract, showing that the reader is a policy-driven parsing layer rather than a heavy computation layer.

7. **vedic-core and report generation**
   `vedic-core` is the **main interpretive analysis engine**. It performs:
   - planet-by-planet audit,
   - D9 cross-checks,
   - house diagnosis,
   - and synthesized life-domain reporting.
   
   Its `resources/` folder contains the interpretive frameworks and QA rules, while `scripts/report_builder.py` suggests it can package analysis into a structured report output.

8. **Specialized downstream analyses**
   `vedic-career` and `vedic-love` are **domain-specific analyzers** that reuse the same chart foundation but focus on different questions:
   - career blueprinting over multiple chart layers,
   - relationship timing and marriage-phase analysis.
   
   `vedic-rectifier` is a separate correction pipeline that uses life events to infer birth time adjustments, and it has its own scan script plus a dedicated event-to-house mapping resource.

9. **vedic-synastry as a separate two-chart boundary**
   `vedic-synastry` is architecturally distinct because it requires **two structured chart inputs**. It performs cross-chart relationship analysis using its own rulebooks and scripts:
   - `build_synastry_data.py`
   - `validate_synastry_data.py`
   
   Its resources encode relationship frameworks, aspect policy, koota policy, and signal triage, which means the logic is rule-heavy and intentionally separated from single-person analysis.

10. **Resources as domain policy, not code**
    The `resources/` directories are an important boundary. They contain interpretation frameworks, validation rules, report rules, and house mappings. These files function like **knowledge and policy packs** that shape how the scripts interpret computed chart data.

11. **Runtime and infrastructure**
    The repo is fundamentally **local Python tooling**, not a networked service. The README indicates support for **Python 3.8–3.13** and no requirement for external APIs. The only bundled infrastructure-like dependency is the ephemeris data shipped inside the calculator skill.

12. **Quality and control model**
    The system emphasizes **validation over guesswork**:
    - environment checks before execution,
    - numeric cross-validation,
    - explicit rule-based analysis,
    - and fail-fast behavior rather than fallback approximations.
    
    For diagramming purposes, the main flow is: **user input → reader/calculator → structured chart data → specialized analysis skills**, with synastry as a separate two-input branch and rectifier as a correction loop.

Main entry points: [`antigravity/skills/vedic-reader/resources/data_contract.md`](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-reader/resources/data_contract.md) (Structured data), [`antigravity/skills/vedic-calculator`](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-calculator) (Calculator), [`antigravity/skills/vedic-core`](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-core) (Core analysis), [`antigravity/skills/vedic-reader`](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-reader) (Reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_canonical["Canonical toolkit"]
  node_skill_suite{{"Skill suite<br/>skill set"}}
  node_calculator["Calculator<br/>chart engine"]
  node_reader["Reader<br/>intake router"]
  node_core["Core analysis<br/>interpretive engine"]
  node_career["Career<br/>domain analyzer"]
  node_love["Love<br/>domain analyzer"]
  node_rectifier["Rectifier<br/>correction pipeline"]
  node_synastry["Synastry<br/>two-chart analyzer"]
  node_structured_data["Structured data<br/>data contract<br/>[data_contract.md]"]
  node_ephe_bundle[("Ephemeris<br/>data bundle")]
  node_setup_env["Setup env<br/>bootstrap script<br/>[setup_env.py]"]
  node_shadbala["Shadbala<br/>correction layer"]
  node_report_builder["Report builder<br/>report assembler<br/>[report_builder.py]"]
  node_reader_rules["Reader rules<br/>policy pack"]
  node_core_rules["Core rules<br/>policy pack<br/>[qa_rules.md]"]
  node_synastry_rules["Synastry rules<br/>policy pack"]
  node_rectifier_map["Event map<br/>mapping pack<br/>[event_house_map.md]"]
end

subgraph group_runtime_antigravity["Antigravity"]
  node_antigravity_pkg["Antigravity skills<br/>runtime package"]
end

subgraph group_runtime_claude["Claude Code"]
  node_claude_pkg["Claude skills<br/>runtime package"]
end

subgraph group_runtime_codex["Codex"]
  node_codex_pkg["Codex skills<br/>runtime package"]
  node_codex_agents["Agent YAML<br/>agent descriptors<br/>[openai.yaml]"]
end

node_repo_root["Repo"]

node_repo_root -->|"contains"| node_skill_suite
node_repo_root -->|"packages"| node_antigravity_pkg
node_repo_root -->|"packages"| node_claude_pkg
node_repo_root -->|"packages"| node_codex_pkg
node_skill_suite -->|"foundation"| node_calculator
node_skill_suite -->|"entry"| node_reader
node_skill_suite -->|"analysis"| node_core
node_skill_suite -->|"specializes"| node_career
node_skill_suite -->|"specializes"| node_love
node_skill_suite -->|"specializes"| node_rectifier
node_skill_suite -->|"specializes"| node_synastry
node_calculator -->|"emits"| node_structured_data
node_reader -->|"validates"| node_structured_data
node_structured_data -->|"feeds"| node_core
node_structured_data -->|"feeds"| node_career
node_structured_data -->|"feeds"| node_love
node_structured_data -->|"feeds"| node_rectifier
node_structured_data -->|"feeds"| node_synastry
node_calculator -->|"depends on"| node_ephe_bundle
node_calculator -->|"bootstraps"| node_setup_env
node_calculator -->|"corrects"| node_shadbala
node_core -->|"packages"| node_report_builder
node_reader -->|"governs"| node_reader_rules
node_core -->|"governs"| node_core_rules
node_synastry -->|"governs"| node_synastry_rules
node_rectifier -->|"governs"| node_rectifier_map
node_codex_pkg -->|"extends"| node_codex_agents
node_antigravity_pkg -.->|"mirrors"| node_skill_suite
node_claude_pkg -.->|"mirrors"| node_skill_suite
node_codex_pkg -.->|"mirrors"| node_skill_suite

click node_calculator "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-calculator"
click node_reader "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-reader"
click node_core "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-core"
click node_career "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-career"
click node_love "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-love"
click node_rectifier "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-rectifier"
click node_synastry "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-synastry"
click node_structured_data "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-reader/resources/data_contract.md"
click node_ephe_bundle "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-calculator/scripts/ephe"
click node_setup_env "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-calculator/scripts/setup_env.py"
click node_shadbala "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-calculator/scripts/shadbala_pyjhora.py"
click node_report_builder "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-core/scripts/report_builder.py"
click node_reader_rules "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-reader/resources/validation_rules.md"
click node_core_rules "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-core/resources/qa_rules.md"
click node_synastry_rules "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-synastry/resources/interpretation-rubric.md"
click node_rectifier_map "https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-rectifier/resources/event_house_map.md"
click node_antigravity_pkg "https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills"
click node_claude_pkg "https://github.com/cnwu16/vedic-astro-skills/tree/main/claude-code/skills"
click node_codex_pkg "https://github.com/cnwu16/vedic-astro-skills/tree/main/codex/skills"
click node_codex_agents "https://github.com/cnwu16/vedic-astro-skills/blob/main/codex/skills/vedic-core/agents/openai.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_suite,node_calculator,node_reader,node_core,node_career,node_love,node_rectifier,node_synastry,node_structured_data,node_ephe_bundle,node_setup_env,node_shadbala,node_report_builder,node_reader_rules,node_core_rules,node_synastry_rules,node_rectifier_map toneBlue
class node_antigravity_pkg toneAmber
class node_claude_pkg toneMint
class node_codex_pkg,node_codex_agents toneRose
class node_repo_root toneNeutral
```

## Components

### Canonical toolkit

Shared astrology skill architecture and data flow.

- **Skill suite**: skill set · Seven mirrored astrology skills organized around a shared chart-data contract.
- [Calculator](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-calculator): chart engine · Computes chart data and emits the canonical structured artifact. · `antigravity/skills/vedic-calculator`
- [Reader](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-reader): intake router · Extracts or verifies birth data from reports and routes usable input onward. · `antigravity/skills/vedic-reader`
- [Core analysis](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-core): interpretive engine · Performs chart interpretation, QA checks, and report synthesis. · `antigravity/skills/vedic-core`
- [Career](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-career): domain analyzer · Career and vocation analysis over the shared chart foundation. · `antigravity/skills/vedic-career`
- [Love](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-love): domain analyzer · Relationship and marriage-focused analysis over the shared chart foundation. · `antigravity/skills/vedic-love`
- [Rectifier](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-rectifier): correction pipeline · Uses life events to infer birth-time adjustments. · `antigravity/skills/vedic-rectifier`
- [Synastry](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-synastry): two-chart analyzer · Performs relationship analysis from two structured charts. · `antigravity/skills/vedic-synastry`
- [Structured data](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-reader/resources/data_contract.md): data contract · Intermediate chart artifact consumed by downstream analysis skills. · `antigravity/skills/vedic-reader/resources/data_contract.md`
- [Ephemeris](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills/vedic-calculator/scripts/ephe): data bundle · Bundled Swiss Ephemeris files used by the calculator. · `antigravity/skills/vedic-calculator/scripts/ephe`
- [Setup env](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-calculator/scripts/setup_env.py): bootstrap script · Provisions and verifies the calculator runtime environment. · `antigravity/skills/vedic-calculator/scripts/setup_env.py`
- [Shadbala](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-calculator/scripts/shadbala_pyjhora.py): correction layer · Shadbala-specific correction logic used by the calculator. · `antigravity/skills/vedic-calculator/scripts/shadbala_pyjhora.py`
- [Report builder](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-core/scripts/report_builder.py): report assembler · Packages core analysis into structured report output. · `antigravity/skills/vedic-core/scripts/report_builder.py`
- [Reader rules](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-reader/resources/validation_rules.md): policy pack · Validation and chart-reading rules for intake and extraction. · `antigravity/skills/vedic-reader/resources/validation_rules.md`
- [Core rules](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-core/resources/qa_rules.md): policy pack · Interpretation frameworks, QA rules, house framework, and yogas. · `antigravity/skills/vedic-core/resources/qa_rules.md`
- [Synastry rules](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-synastry/resources/interpretation-rubric.md): policy pack · Aspect, koota, triage, and relationship frameworks. · `antigravity/skills/vedic-synastry/resources/interpretation-rubric.md`
- [Event map](https://github.com/cnwu16/vedic-astro-skills/blob/main/antigravity/skills/vedic-rectifier/resources/event_house_map.md): mapping pack · Event-to-house mapping used by the rectification pipeline. · `antigravity/skills/vedic-rectifier/resources/event_house_map.md`

### Antigravity

Antigravity packaging of the skill set.

- [Antigravity skills](https://github.com/cnwu16/vedic-astro-skills/tree/main/antigravity/skills): runtime package · Antigravity distribution of the shared skill set. · `antigravity/skills`

### Claude Code

Claude Code packaging of the skill set.

- [Claude skills](https://github.com/cnwu16/vedic-astro-skills/tree/main/claude-code/skills): runtime package · Claude Code distribution of the shared skill set. · `claude-code/skills`

### Codex

Codex packaging of the skill set and agent descriptors.

- [Codex skills](https://github.com/cnwu16/vedic-astro-skills/tree/main/codex/skills): runtime package · Codex distribution of the shared skill set and agent descriptors. · `codex/skills`
- [Agent YAML](https://github.com/cnwu16/vedic-astro-skills/blob/main/codex/skills/vedic-core/agents/openai.yaml): agent descriptors · Codex-specific OpenAI agent descriptors for selected skills. · `codex/skills/vedic-core/agents/openai.yaml`

### Other components

- **Repo**: monorepo · Multi-runtime astrology skill repository.

## Connections

- Repo → Skill suite: contains · Repository contains the shared astrology skill architecture.
- Repo → Antigravity skills: packages · Antigravity distribution of the toolkit.
- Repo → Claude skills: packages · Claude Code distribution of the toolkit.
- Repo → Codex skills: packages · Codex distribution of the toolkit.
- Skill suite → Calculator: foundation · Chart computation is the authoritative source for downstream analysis.
- Skill suite → Reader: entry · Reader routes and validates user input before analysis.
- Skill suite → Core analysis: analysis · Core performs the primary interpretive pass.
- Skill suite → Career: specializes · Career analysis reuses the shared chart foundation.
- Skill suite → Love: specializes · Love analysis reuses the shared chart foundation.
- Skill suite → Rectifier: specializes · Rectifier infers time corrections from life events.
- Skill suite → Synastry: specializes · Synastry analyzes relationships using two chart inputs.
- Calculator → Structured data: emits · Calculator produces the canonical structured chart artifact.
- Reader → Structured data: validates · Reader checks extracted or provided chart data against the contract.
- Structured data → Core analysis: feeds · Core consumes the canonical chart artifact.
- Structured data → Career: feeds · Career analysis consumes the canonical chart artifact.
- Structured data → Love: feeds · Love analysis consumes the canonical chart artifact.
- Structured data → Rectifier: feeds · Rectifier consumes chart data plus event context.
- Structured data → Synastry: feeds · Synastry consumes structured charts for each person.
- Calculator → Ephemeris: depends on · Local ephemeris data underpins chart computation.
- Calculator → Setup env: bootstraps · Environment setup is part of the calculator execution model.
- Calculator → Shadbala: corrects · Shadbala logic refines strength calculations.
- Core analysis → Report builder: packages · Core can assemble structured report output.
- Reader → Reader rules: governs · Intake and extraction are policy-driven.
- Core analysis → Core rules: governs · Interpretation and QA are rule-driven.
- Synastry → Synastry rules: governs · Relationship analysis is driven by dedicated rulebooks.
- Rectifier → Event map: governs · Event-to-house mapping guides rectification logic.
- Codex skills → Agent YAML: extends · Codex mirrors include agent descriptors alongside skills.
- Antigravity skills → Skill suite: mirrors · Antigravity mirrors the canonical skill set.
- Claude skills → Skill suite: mirrors · Claude Code mirrors the canonical skill set.
- Codex skills → Skill suite: mirrors · Codex mirrors the canonical skill set.