# socraticsurge/telugu-calendar-utilities architecture

> Architecture diagram of the GitHub repository socraticsurge/telugu-calendar-utilities, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/socraticsurge/telugu-calendar-utilities
- Repository: https://github.com/socraticsurge/telugu-calendar-utilities

## Overview

Telugu Panchangam is both a city-specific calendar-feed generator and a daily astrology toolkit exposed through a browser UI and an MCP server. Users select a city, date, and calculation system to view Panchangam details or subscribe to an ICS feed; they can also search activity-aware muhurta windows, assess personal tarabalam, and explore gochara readings. Python calculation engines produce shared day facts for feed generation and MCP tools, while the TypeScript application coordinates browser panels and profile workflows. The README documents capabilities beyond the sampled source, so those subsystem links are shown only where the documentation supports them.

Main entry points: [`src/main.ts`](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/main.ts) (Browser application), [`telugu_panchangam/mcp/tools.py`](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/mcp/tools.py) (MCP tools), [`telugu_panchangam/personal/muhurta_search.py`](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/muhurta_search.py) (Muhurta search), [`telugu_panchangam/engines/base.py`](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/base.py) (Engine day assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser toolkit"]
  node_webapp["Browser application<br/>[main.ts]"]
  node_today["Today's Panchangam<br/>[today.ts]"]
  node_gochara_ui["Gochara panel<br/>[gochara.ts]"]
  node_profiles["Guest profiles<br/>[profiles.ts]"]
  node_profile_store[("Profile store")]
  node_tarabalam_ui["Tarabalam and muhurta<br/>[tarabalam.ts]"]
  node_mu_search_ui["Muhurta search UI<br/>[muhurta-search.ts]"]
  node_day_pipeline["Muhurta day pipeline"]
  node_mu_scoring["Muhurta scoring<br/>[muhurta-scoring.ts]"]
  node_chart_screening["Chart screening"]
end

subgraph group_calc["Calendar calculation"]
  node_engine_base["Engine day assembly<br/>[base.py]"]
  node_drik["Drik engine<br/>[drik.py]"]
  node_surya["Surya Siddhanta engine<br/>[surya_siddhanta.py]"]
  node_vakya["Vakya engine<br/>[vakya.py]"]
  node_day_model["Panchangam day facts<br/>[panchangam_day.py]"]
  node_shuddhi["Panchanga Shuddhi"]
end

subgraph group_personal["Personal astrology"]
  node_personal_search["Muhurta search<br/>[muhurta_search.py]"]
  node_activity_rules["Activity rules<br/>[activity_rules.py]"]
  node_election["Personal election"]
end

subgraph group_delivery["Feeds and services"]
  node_ics["ICS feed generation<br/>[ics.py]"]
  node_feed_gen["Feed generation entry<br/>[generate.py]"]
end

subgraph group_mcp["MCP interface"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
end

node_visitor(("Calendar user"))
node_mcp_client(("MCP client"))
node_calculation_service{{"Chart calculation service"}}
node_calendar_apps(("Calendar applications"))

node_visitor -->|"uses"| node_webapp
node_webapp -->|"loads and renders"| node_today
node_webapp -->|"loads"| node_gochara_ui
node_webapp -->|"renders"| node_tarabalam_ui
node_webapp -->|"initializes"| node_profiles
node_webapp -->|"creates"| node_profile_store
node_profiles -.->|"uses"| node_profile_store
node_tarabalam_ui -.->|"renders"| node_mu_search_ui
node_mu_search_ui -->|"coordinates"| node_day_pipeline
node_day_pipeline -->|"uses"| node_mu_scoring
node_mu_scoring -->|"screens candidates"| node_chart_screening
node_chart_screening -.->|"requests chart"| node_calculation_service
node_drik -->|"uses base"| node_engine_base
node_surya -.->|"uses base"| node_engine_base
node_vakya -.->|"uses base"| node_engine_base
node_engine_base -->|"assembles facts"| node_day_model
node_day_model -->|"assessed by"| node_shuddhi
node_personal_search -->|"calculates days"| node_drik
node_personal_search -->|"loads rules"| node_activity_rules
node_personal_search -->|"collects results"| node_day_model
node_visitor -->|"subscribes"| node_calendar_apps
node_feed_gen -->|"generates feeds"| node_ics
node_ics -->|"formats day facts"| node_day_model
node_ics -->|"provides ICS"| node_calendar_apps
node_mcp_client -->|"connects"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"calculates calendar"| node_drik
node_mcp_tools -->|"searches muhurtas"| node_personal_search
node_mcp_tools -.->|"offers personal tools"| node_election

click node_webapp "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/main.ts"
click node_today "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/today.ts"
click node_gochara_ui "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/gochara.ts"
click node_profiles "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/profiles.ts"
click node_profile_store "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/lib/guest-profile-store.ts"
click node_tarabalam_ui "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/tarabalam.ts"
click node_mu_search_ui "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/muhurta-search.ts"
click node_day_pipeline "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/muhurta-day-pipeline.ts"
click node_mu_scoring "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/muhurta-scoring.ts"
click node_chart_screening "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/scorer/election-chart-screening.ts"
click node_engine_base "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/base.py"
click node_drik "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/drik.py"
click node_surya "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/surya_siddhanta.py"
click node_vakya "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/vakya.py"
click node_day_model "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/models/panchangam_day.py"
click node_shuddhi "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/panchanga_shuddhi.py"
click node_personal_search "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/muhurta_search.py"
click node_activity_rules "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/activity_rules.py"
click node_election "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/personal_election.py"
click node_ics "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/generators/ics.py"
click node_feed_gen "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/generate.py"
click node_mcp_server "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/mcp/server.py"
click node_mcp_tools "https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/mcp/tools.py"

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_webapp,node_today,node_gochara_ui,node_profiles,node_profile_store,node_tarabalam_ui,node_mu_search_ui,node_day_pipeline,node_mu_scoring,node_chart_screening,node_visitor,node_mcp_client toneBlue
class node_engine_base,node_drik,node_surya,node_vakya,node_day_model,node_shuddhi toneAmber
class node_personal_search,node_activity_rules,node_election toneMint
class node_ics,node_feed_gen toneRose
class node_mcp_server,node_mcp_tools,node_calculation_service,node_calendar_apps toneIndigo
```

## Components

### Browser toolkit

- [Browser application](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/main.ts): `src/main.ts`
- [Today's Panchangam](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/today.ts): `src/panels/today.ts`
- [Gochara panel](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/gochara.ts): `src/panels/gochara.ts`
- [Guest profiles](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/profiles.ts): `src/panels/profiles.ts`
- [Profile store](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/lib/guest-profile-store.ts): `src/lib/guest-profile-store.ts`
- [Tarabalam and muhurta](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/tarabalam.ts): `src/panels/tarabalam.ts`
- [Muhurta search UI](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/muhurta-search.ts): `src/panels/muhurta-search.ts`
- [Muhurta day pipeline](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/muhurta-day-pipeline.ts): `src/panels/muhurta-day-pipeline.ts`
- [Muhurta scoring](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/panels/muhurta-scoring.ts): `src/panels/muhurta-scoring.ts`
- [Chart screening](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/src/scorer/election-chart-screening.ts): `src/scorer/election-chart-screening.ts`

### Calendar calculation

- [Engine day assembly](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/base.py): `telugu_panchangam/engines/base.py`
- [Drik engine](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/drik.py): `telugu_panchangam/engines/drik.py`
- [Surya Siddhanta engine](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/surya_siddhanta.py): `telugu_panchangam/engines/surya_siddhanta.py`
- [Vakya engine](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/engines/vakya.py): `telugu_panchangam/engines/vakya.py`
- [Panchangam day facts](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/models/panchangam_day.py): `telugu_panchangam/models/panchangam_day.py`
- [Panchanga Shuddhi](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/panchanga_shuddhi.py): `telugu_panchangam/panchanga_shuddhi.py`

### Personal astrology

- [Muhurta search](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/muhurta_search.py): `telugu_panchangam/personal/muhurta_search.py`
- [Activity rules](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/activity_rules.py): `telugu_panchangam/personal/activity_rules.py`
- [Personal election](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/personal/personal_election.py): `telugu_panchangam/personal/personal_election.py`

### Feeds and services

- [ICS feed generation](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/generators/ics.py): `telugu_panchangam/generators/ics.py`
- [Feed generation entry](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/generate.py): `telugu_panchangam/generate.py`

### MCP interface

- [MCP server](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/mcp/server.py): `telugu_panchangam/mcp/server.py`
- [MCP tools](https://github.com/socraticsurge/telugu-calendar-utilities/blob/master/telugu_panchangam/mcp/tools.py): `telugu_panchangam/mcp/tools.py`

### Other components

- **Calendar user**
- **MCP client**
- **Chart calculation service**
- **Calendar applications**

## Connections

- Calendar user → Browser application: uses (evidence: `README.md`)
- Browser application → Today's Panchangam: loads and renders (evidence: `src/main.ts`)
- Browser application → Gochara panel: loads (evidence: `src/main.ts`)
- Browser application → Tarabalam and muhurta: renders (evidence: `src/main.ts`)
- Browser application → Guest profiles: initializes (evidence: `src/main.ts`)
- Browser application → Profile store: creates (evidence: `src/main.ts`)
- Guest profiles → Profile store: uses
- Tarabalam and muhurta → Muhurta search UI: renders
- Muhurta search UI → Muhurta day pipeline: coordinates (evidence: `src/panels/muhurta-search.ts`)
- Muhurta day pipeline → Muhurta scoring: uses (evidence: `src/panels/muhurta-day-pipeline.ts`)
- Muhurta scoring → Chart screening: screens candidates (evidence: `src/panels/muhurta-scoring.ts`)
- Chart screening → Chart calculation service: requests chart
- Drik engine → Engine day assembly: uses base (evidence: `telugu_panchangam/engines/base.py`)
- Surya Siddhanta engine → Engine day assembly: uses base
- Vakya engine → Engine day assembly: uses base
- Engine day assembly → Panchangam day facts: assembles facts (evidence: `telugu_panchangam/engines/base.py`)
- Panchangam day facts → Panchanga Shuddhi: assessed by (evidence: `telugu_panchangam/panchanga_shuddhi.py`)
- Muhurta search → Drik engine: calculates days (evidence: `telugu_panchangam/personal/muhurta_search.py`)
- Muhurta search → Activity rules: loads rules (evidence: `telugu_panchangam/personal/muhurta_search.py`)
- Muhurta search → Panchangam day facts: collects results (evidence: `telugu_panchangam/personal/muhurta_search.py`)
- Calendar user → Calendar applications: subscribes (evidence: `README.md`)
- Feed generation entry → ICS feed generation: generates feeds (evidence: `README.md`)
- ICS feed generation → Panchangam day facts: formats day facts (evidence: `telugu_panchangam/generators/ics.py`)
- ICS feed generation → Calendar applications: provides ICS (evidence: `README.md`)
- MCP client → MCP server: connects (evidence: `README.md`)
- MCP server → MCP tools: dispatches tools (evidence: `telugu_panchangam/mcp/server.py`)
- MCP tools → Drik engine: calculates calendar (evidence: `telugu_panchangam/mcp/tools.py`)
- MCP tools → Muhurta search: searches muhurtas (evidence: `telugu_panchangam/mcp/tools.py`)
- MCP tools → Personal election: offers personal tools
