# d-evil0per/ai_astrology_agent architecture

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

- Interactive diagram: https://gitdiagram.com/d-evil0per/ai_astrology_agent
- Repository: https://github.com/d-evil0per/ai_astrology_agent

## Overview

##### Project type and purpose
- This is a backend, AI-powered astrology agent library/service (“ai_astrology_agent”).
- It ingests raw ephemeris files, computes astrological charts, generates natural-language interpretations, and can answer astrology-related queries.

##### File structure
- Top level
– app.py: entry point (CLI/web‐service starter)
– requirements.txt: Python dependencies
– data/ephe/: directory of raw ephemeris files (satellite, lunar, solar, planetary)
– src/: core modules
- src modules
– chart_calculator.py: reads ephemeris data + computes planetary positions and aspects
– interpretation_generator.py: crafts human-readable astrology interpretations (likely uses an AI model)
– qa_agent.py: wraps chart logic + interpretation in a Q&A interface (probably prompts an LLM)
- No frontend/UI; it’s a backend-only pipeline.

##### README
- Minimal. Title indicates it’s a test or PoC astrology agent.

##### Additional notes
- If app.py uses an HTTP framework, annotate the API endpoints.
- Logging/metrics if relevant (e.g., export Prometheus metrics).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interface
    Client["Client Interface\n(CLI / HTTP)"]:::interface
    click Client "https://github.com/d-evil0per/ai_astrology_agent/blob/main/app.py"

    %% Development Environment
    subgraph "Development Environment"
        DevContainer["DevContainer\n(.devcontainer)"]:::devEnv
        click DevContainer "https://github.com/d-evil0per/ai_astrology_agent/blob/main/.devcontainer/devcontainer.json"
        Requirements["Python Dependencies\n(requirements.txt)"]:::devEnv
        click Requirements "https://github.com/d-evil0per/ai_astrology_agent/blob/main/requirements.txt"
    end

    %% Backend Components
    subgraph "Backend Service"
        direction TB
        App["app.py\n(Application Server)"]:::interface
        click App "https://github.com/d-evil0per/ai_astrology_agent/blob/main/app.py"

        subgraph "Core Pipeline"
            direction TB
            QA["QA Agent\n(src/qa_agent.py)"]:::compute
            click QA "https://github.com/d-evil0per/ai_astrology_agent/blob/main/src/qa_agent.py"

            ChartCalc["Chart Calculator\n(src/chart_calculator.py)"]:::compute
            click ChartCalc "https://github.com/d-evil0per/ai_astrology_agent/blob/main/src/chart_calculator.py"

            InterpretGen["Interpretation Generator\n(src/interpretation_generator.py)"]:::compute
            click InterpretGen "https://github.com/d-evil0per/ai_astrology_agent/blob/main/src/interpretation_generator.py"
        end

        subgraph "Data Store"
            direction TB
            Ephemeris["Ephemeris Data Store\n(data/ephe/)"]:::dataStore
            click Ephemeris "https://github.com/d-evil0per/ai_astrology_agent/tree/main/data/ephe/"
        end

        subgraph "Logging & Monitoring"
            Logs["Logging / Metrics"]:::external
        end
    end

    %% External Services
    ExternalAI["External AI Service\n(LLM API)"]:::external

    %% Connections
    Client -->|"request"| App
    App -->|"invoke"| QA
    QA -->|"compute chart"| ChartCalc
    ChartCalc -->|"read ephemeris"| Ephemeris
    ChartCalc -->|"return chart data"| QA
    QA -->|"generate interpretation"| InterpretGen
    InterpretGen -->|"return text"| QA
    QA -->|"call LLM"| ExternalAI
    QA -->|"log activity"| Logs
    App -->|"response"| Client

    %% Styles
    classDef interface fill:#DDEBF7,stroke:#1155CC,color:#1155CC;
    classDef compute fill:#E2EFDA,stroke:#6AA84F,color:#274E13;
    classDef dataStore fill:#DEEAF6,stroke:#1C4587,color:#1C4587;
    classDef external fill:#FCE4D6,stroke:#E69138,color:#8C4600;
    classDef devEnv fill:#FFF2CC,stroke:#BF9000,color:#573A08;
```
