# g-battaglia/kerykeion architecture

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

- Interactive diagram: https://gitdiagram.com/g-battaglia/kerykeion
- Repository: https://github.com/g-battaglia/kerykeion

## Overview

##### Main Components
- Core Astrology Engine:
- This includes the AstrologicalSubject class (the core “entity” of an individual’s astrological data) and supporting calculations from modules like kerykeion/kr_types, kerykeion/aspects, kerykeion/relationship_score, and kerykeion/enums. These handle point/planet calculations, house systems, zodiac configuration, perspective type, and aspect calculations.
- Chart Generation Component:
- Modules under kerykeion/charts (including templates and themes) and the KerykeionChartSVG class are responsible for generating SVG representations of different types of charts (birth, synastry, transit, composite). This component interacts with the core astrology engine to render visual outputs.
- Report Module:
- The Report class and supporting utilities (like kerykeion/report.py) consolidate astrological data into human-readable text formats.
- Configuration and Settings:
- This includes kerykeion/settings and the configuration file (kr.config.json) that allow users to set custom parameters (like zodiac type, houses system, language, and other constants used by different modules).
- External Data Interfaces:
- The project optionally uses online geolocation (via kerykeion/fetch_geonames.py) and Swiss Ephemeris data (under kerykeion/sweph) for accurate planetary data.
- Utility and Factory Modules:
- Modules like composite_subject_factory.py and utilities.py are support layers providing additional functionalities (e.g., combining two subjects into a composite chart).

##### Relationships and Interactions
- The AstrologicalSubject acts as the input gateway: it aggregates user input (e.g., birth date, coordinates) and initializes core calculations.
- Once the subject is created, different submodules (aspects, charts, report, etc.) consume this data:
- The aspects modules compute astrological relationships.
- The charts modules generate SVG visuals by taking in data from the subject.
- The report module compiles data into tabular or textual reports.
- Configuration and settings are pulled in by almost every module, ensuring different calculation modes (houses system, perspective, sidereal/tropical, etc.) are consistently applied.
- External data (GeoNames and Swiss Ephemeris) feeds into the AstrologicalSubject to enrich or adjust computation logic based on location and astronomical data.

##### Architectural Design Patterns and Design Principles
- Modularity: The project is clearly separated into self-contained modules catering to calculation, visualization, and reporting.
- Data Flow Orientation: Inputs (subject data and configuration) flow into the core engine, which then feeds calculated outputs to multiple consumers (e.g., charts, report, aspects, etc.).
- Extensibility: The use of factories (e.g., CompositeSubjectFactory) and utility modules, along with clearly defined enum types, means the system is designed to be extensible for future astrological features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input and Configuration
    subgraph "Input and Configuration"
        A["User/Config Input"]
        B["Configuration & Settings"]:::config
        C["Configuration File"]:::config
        A --> B
        B --> C
    end

    %% Core Astrology Engine
    subgraph "Core Astrology Engine"
        D["AstrologicalSubject & Core Calculations"]:::core
        E["kr_types"]:::core
        F["Natal Aspects"]:::core
        G["Synastry Aspects"]:::core
        H["Relationship Score"]:::core
        I["Enums"]:::core
        B --> D
        D --> E
        D --> F
        D --> G
        D --> H
        D --> I
    end

    %% External Data Interfaces
    subgraph "External Data Interfaces"
        J["Online Geolocation"]:::external
        K["Swiss Ephemeris"]:::external
    end

    %% Output Generation
    subgraph "Output Generation"
        L["Chart Generation Component"]:::chart
        M["SVG Chart Generator"]:::chart
        N["Chart Templates"]:::chart
        O["Chart Themes"]:::chart
        P["Report Module"]:::report
        L --> M
        L --> N
        L --> O
    end

    %% Utility and Factory Modules
    subgraph "Utility & Factory Modules"
        Q["Composite Subject Factory"]:::utility
        R["Utility Functions"]:::utility
    end

    %% Data Flow Connections
    A -->|"input"| D
    J --- D
    K --- D
    D -->|"chart_data"| L
    D -->|"report_data"| P
    D -->|"composite_input"| Q
    D --> R
    B --- L
    B --- P

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef chart fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef report fill:#C1FFC1,stroke:#000,stroke-width:1px;
    classDef config fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef external fill:#FFD580,stroke:#000,stroke-width:1px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events
    click D "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/astrological_subject.py"
    click E "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/kr_types"
    click F "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/aspects/natal_aspects.py"
    click G "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/aspects/synastry_aspects.py"
    click H "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/relationship_score"
    click I "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/enums.py"
    click B "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/settings"
    click C "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/settings/kr.config.json"
    click J "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/fetch_geonames.py"
    click K "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/sweph"
    click L "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/charts"
    click M "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/charts/kerykeion_chart_svg.py"
    click N "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/charts/templates"
    click O "https://github.com/g-battaglia/kerykeion/tree/master/kerykeion/charts/themes"
    click P "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/report.py"
    click Q "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/composite_subject_factory.py"
    click R "https://github.com/g-battaglia/kerykeion/blob/master/kerykeion/utilities.py"
```
