# hoishing/natal architecture

> Architecture diagram of the GitHub repository hoishing/natal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hoishing/natal
- Repository: https://github.com/hoishing/natal

## Overview

Based on our analysis of the file tree and README, “Natal” is a Python library for generating astrological (natal and composite) charts in SVG format. The project’s purpose is to provide a highly configurable system for computing and rendering astrological data—and even generating statistical analysis and reports from that data—using pure Python. The system is designed as a library (with integrations in both scripts and interactive environments such as Jupyter) and includes comprehensive testing and documentation.

##### Main Components
- Data and Domain Model: The core “Data” object (see natal/data.py) represents all the astrological inputs (birth time, location, etc.) and computes positions of celestial bodies (planets, houses, aspects). Other domain objects are defined in modules such as natal/classes.py, natal/const.py, and natal/config.py.
- Chart Generation Module: The “Chart” module (natal/chart.py) takes one or two Data objects (for natal/transit, composite charts, etc.) and generates an SVG chart. It leverages the “tagit” library for SVG/HTML generation and may invoke utilities for SVG path cleanup (natal/svg_paths/clean_up.py).
- Statistics and Reporting: The “Stats” module (natal/stats.py) provides functionality to generate statistical reports (in Markdown or HTML) based on the astrological data. This is useful for the analysis and cross-referencing of aspects, houses, etc.
- Configuration Management: The natal/config.py (and related files) provide ways for users to override default settings, customize themes (light, dark, mono), control which celestial objects display, and adjust other visual parameters.
- External Dependencies/Services:
- pyswisseph is used for high-precision astrological calculations.
- tagit is used for generating and manipulating the SVG output.
- mkdocs-material is present to generate the documentation website (docs, mkdocs.yml).
- Optional PDF generation integrates with the natal-report package.
- Testing Suite: The “tests” directory covers unit tests for major components such as chart creation, config handling, constants, data processing, stats, and utilities.
- Developer & CI/CD Tools: GitHub Actions workflows help with continuous integration; configuration files like pyproject.toml and .gitignore define build/test settings.

##### Relationships and Interactions
- The Data Object receives input parameters (name, UTC datetime, latitude, longitude, and optional config) and initializes domain objects (planets, houses, etc.) using pyswisseph.
- The Chart Module consumes the Data object(s) to generate an SVG chart. It interfaces with tagit for the rendering and with the SVG path utilities for refining the output.
- The Stats Module analyzes a Data object (or two for composite charts) and produces textual reports (Markdown/HTML).
- The Config module customizes behavior and appearance, and its objects can be passed into the Data object.
- Testing components are standalone, verifying each component’s correctness.

##### Architectural Patterns and Design Principles
- Modular design: Each domain (Data, Chart, Stats, Config, Utils) exists as separate modules under the “natal” package.
- Separation of concerns: Data processing (e.g., calculating astronomical data), visual rendering, and reporting are all managed in dedicated components.
- Dependency injection: Custom configurations and state are injected into Data and Chart objects to allow flexibility.
- Extensibility: The design allows adding additional chart types or reports (e.g., composite charts, PDF reports) without altering core functionality.

##### Relevant Technologies and Libraries
- Python as the core language.
- pyswisseph for astronomy/astrological calculations.
- tagit for SVG/HTML manipulation.
- MkDocs (with mkdocs-material theme) for documentation generation.
- Pytest for testing.
- GitHub Actions for CI/CD.

##### Specific Elements
- Use clear labels to denote:
- Data Input Component (Data object with configuration)
- Domain Logic (Modules like classes, consts, config)
- Chart Generation Component (Chart module interfacing with tagit and SVG Path utilities)
- Statistics/Reporting Component (Stats module)
- External Dependencies (pyswisseph, tagit, mkdocs-material)
- Tests and CI/CD components (tests directory, GitHub workflows)
- From Input (Data, Config) to Processing (Chart computation and Stats generation)
- From Processing to Output (SVG chart, Markdown/HTML/PDF reports)
- Differentiate between domain modules, external libraries, developer tools, and testing/infrastructure.
- For example, rectangles for core modules, ellipses for external services, and parallelograms for input/output interfaces.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Domain Modules
    subgraph "Core Domain Modules"
        Data["Data (Core)"]:::core
        Classes["Domain Classes"]:::core
        Constants["Constants"]:::core
        Config["Configuration"]:::core
    end

    %% Chart Generation Module
    subgraph "Chart Generation"
        Chart["Chart Generator"]:::core
        SVG_Clean["SVG Cleaner"]:::core
    end

    %% Statistics and Reporting
    subgraph "Statistics & Reporting"
        Stats["Stats Reporter"]:::core
    end

    %% External Libraries
    subgraph "External Libraries"
        SW["pyswisseph"]:::external
        Tagit["tagit"]:::external
        MkDocsMat["mkdocs-material"]:::external
        NatalReport["natal-report"]:::external
    end

    %% Testing Suite
    subgraph "Testing Suite"
        Test_Chart["Chart Test"]:::test
        Test_Config["Config Test"]:::test
        Test_Const["Const Test"]:::test
        Test_Data["Data Test"]:::test
        Test_Stats["Stats Test"]:::test
        Test_Utils["Utils Test"]:::test
    end

    %% Developer & CI/CD Tools
    subgraph "Developer & CI/CD"
        CI["CI Workflow"]:::cicd
        BuildConfig["Build Config"]:::cicd
        GitIgnore["Git Ignore"]:::cicd
    end

    %% Documentation and Reporting
    subgraph "Documentation"
        Docs["Documentation Files"]:::docs
        MkDocs["MkDocs Config"]:::docs
    end

    %% Relationships
    Config -->|"injects"| Data
    Classes -->|"initiates"| Data
    Constants -->|"supports"| Data
    Data -->|"provides"| Chart
    Data -->|"provides"| Stats
    Chart -->|"cleans"| SVG_Clean
    SW -->|"calculates"| Data
    Tagit -->|"renders"| Chart
    Stats -->|"generates"| NatalReport
    MkDocsMat -->|"themes"| Docs

    CI -->|"triggers"| Test_Chart
    CI -->|"triggers"| Test_Config
    CI -->|"triggers"| Test_Const
    CI -->|"triggers"| Test_Data
    CI -->|"triggers"| Test_Stats
    CI -->|"triggers"| Test_Utils

    CI -->|"verifies"| Data
    CI -->|"verifies"| Chart
    CI -->|"verifies"| Stats

    Test_Chart -->|"tests"| Chart
    Test_Config -->|"tests"| Config
    Test_Const -->|"tests"| Constants
    Test_Data -->|"tests"| Data
    Test_Stats -->|"tests"| Stats
    Test_Utils -->|"tests"| Data

    BuildConfig -->|"configures"| Data
    BuildConfig -->|"configures"| Chart
    BuildConfig -->|"configures"| Stats

    %% Click Events for Core Domain Modules
    click Data "https://github.com/hoishing/natal/blob/main/natal/data.py"
    click Classes "https://github.com/hoishing/natal/blob/main/natal/classes.py"
    click Constants "https://github.com/hoishing/natal/blob/main/natal/const.py"
    click Config "https://github.com/hoishing/natal/blob/main/natal/config.py"

    %% Click Events for Chart Generation Module
    click Chart "https://github.com/hoishing/natal/blob/main/natal/chart.py"
    click SVG_Clean "https://github.com/hoishing/natal/blob/main/natal/svg_paths/clean_up.py"

    %% Click Event for Statistics and Reporting
    click Stats "https://github.com/hoishing/natal/blob/main/natal/stats.py"

    %% Click Events for Testing Suite
    click Test_Chart "https://github.com/hoishing/natal/blob/main/tests/test_chart.py"
    click Test_Config "https://github.com/hoishing/natal/blob/main/tests/test_config.py"
    click Test_Const "https://github.com/hoishing/natal/blob/main/tests/test_const.py"
    click Test_Data "https://github.com/hoishing/natal/blob/main/tests/test_data.py"
    click Test_Stats "https://github.com/hoishing/natal/blob/main/tests/test_stats.py"
    click Test_Utils "https://github.com/hoishing/natal/blob/main/tests/test_utils.py"

    %% Click Events for Developer & CI/CD Tools
    click CI "https://github.com/hoishing/natal/blob/main/.github/workflows/ci.yml"
    click BuildConfig "https://github.com/hoishing/natal/blob/main/pyproject.toml"
    click GitIgnore "https://github.com/hoishing/natal/blob/main/.gitignore"

    %% Click Events for Documentation and Reporting
    click Docs "https://github.com/hoishing/natal/tree/main/docs"
    click MkDocs "https://github.com/hoishing/natal/blob/main/mkdocs.yml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef test fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef cicd fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef docs fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
