# maanavar/sanstro architecture

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

- Interactive diagram: https://gitdiagram.com/maanavar/sanstro
- Repository: https://github.com/maanavar/sanstro

## Overview

Vinaadi AI is a Tamil-first bilingual astrology companion with Expo mobile and Next.js web clients backed by a FastAPI service. The user-facing path runs from account and birth details to chart generation, then to personalized readings, daily guidance, and tools such as panchangam and muhurta. The backend also covers numerology, relationships, notifications, and personal records. The graph reflects documented client/API boundaries and sampled module references; several domain implementations are unsampled, so their internal call paths are not asserted.

Main entry points: [`app/main.py`](https://github.com/maanavar/sanstro/blob/main/app/main.py) (FastAPI app), [`app/api/public_tools.py`](https://github.com/maanavar/sanstro/blob/main/app/api/public_tools.py) (Public tools), [`app/api/charts.py`](https://github.com/maanavar/sanstro/blob/main/app/api/charts.py) (Chart endpoints), [`app/services/narrative_engine.py`](https://github.com/maanavar/sanstro/blob/main/app/services/narrative_engine.py) (Narrative guidance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_mobile["Mobile app"]
  node_web["Web app"]
  node_shared["Shared API package"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_profiles["Birth profiles<br/>[birth_profiles.py]"]
  node_chart_api["Chart endpoints<br/>[charts.py]"]
  node_tools_api["Public tools<br/>[public_tools.py]"]
end

subgraph group_astro["Astrology and guidance"]
  node_charts["Chart calculations<br/>[astro.py]"]
  node_strength["Chart strength<br/>[chart_strength.py]"]
  node_names["Astrology display names<br/>[display_names.py]"]
  node_narrative["Narrative guidance"]
  node_daily["Daily guidance"]
  node_panchangam["Panchangam<br/>[panchangam.py]"]
  node_transits["Transits<br/>[transits.py]"]
  node_muhurta["Muhurta<br/>[muhurta_engine.py]"]
  node_numerology["Numerology<br/>[numerology.py]"]
end

subgraph group_platform["Data and operations"]
  node_db["Database sessions<br/>[session.py]"]
  node_models[("Domain records")]
  node_config["Configuration<br/>[config.py]"]
  node_age_gate["Age gate<br/>[age_gate.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_web
node_mobile -->|"uses API"| node_shared
node_web -->|"proxies requests"| node_app
node_mobile -->|"calls API"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_profiles
node_app -->|"registers routes"| node_chart_api
node_app -->|"registers routes"| node_tools_api
node_auth -->|"opens session"| node_db
node_profiles -->|"opens session"| node_db
node_chart_api -->|"uses calculations"| node_charts
node_chart_api -->|"uses calculations"| node_strength
node_narrative -->|"uses calculations"| node_charts
node_narrative -->|"uses calculations"| node_strength
node_narrative -->|"uses labels"| node_names
node_tools_api -.->|"exposes tool"| node_muhurta
node_tools_api -.->|"exposes tool"| node_panchangam
node_tools_api -.->|"exposes tool"| node_numerology
node_db -->|"reads settings"| node_config
node_db -->|"persists records"| node_models
node_chart_api -->|"checks access"| node_age_gate
node_tools_api -.->|"offers astrology"| node_transits
node_daily -.->|"builds guidance"| node_narrative

click node_mobile "https://github.com/maanavar/sanstro/tree/main/mobile/app"
click node_web "https://github.com/maanavar/sanstro/tree/main/web/app"
click node_shared "https://github.com/maanavar/sanstro/tree/main/packages/shared/src/api"
click node_app "https://github.com/maanavar/sanstro/blob/main/app/main.py"
click node_auth "https://github.com/maanavar/sanstro/blob/main/app/api/auth.py"
click node_profiles "https://github.com/maanavar/sanstro/blob/main/app/api/birth_profiles.py"
click node_chart_api "https://github.com/maanavar/sanstro/blob/main/app/api/charts.py"
click node_tools_api "https://github.com/maanavar/sanstro/blob/main/app/api/public_tools.py"
click node_charts "https://github.com/maanavar/sanstro/blob/main/app/calculations/astro.py"
click node_strength "https://github.com/maanavar/sanstro/blob/main/app/calculations/chart_strength.py"
click node_names "https://github.com/maanavar/sanstro/blob/main/app/calculations/display_names.py"
click node_narrative "https://github.com/maanavar/sanstro/blob/main/app/services/narrative_engine.py"
click node_daily "https://github.com/maanavar/sanstro/blob/main/app/services/daily_guidance_service.py"
click node_panchangam "https://github.com/maanavar/sanstro/blob/main/app/calculations/panchangam.py"
click node_transits "https://github.com/maanavar/sanstro/blob/main/app/calculations/transits.py"
click node_muhurta "https://github.com/maanavar/sanstro/blob/main/app/calculations/muhurta_engine.py"
click node_numerology "https://github.com/maanavar/sanstro/blob/main/app/calculations/numerology.py"
click node_db "https://github.com/maanavar/sanstro/blob/main/app/db/session.py"
click node_models "https://github.com/maanavar/sanstro/tree/main/app/models"
click node_config "https://github.com/maanavar/sanstro/blob/main/app/core/config.py"
click node_age_gate "https://github.com/maanavar/sanstro/blob/main/app/core/age_gate.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_mobile,node_web,node_shared,node_user toneBlue
class node_app,node_auth,node_profiles,node_chart_api,node_tools_api toneAmber
class node_charts,node_strength,node_names,node_narrative,node_daily,node_panchangam,node_transits,node_muhurta,node_numerology toneMint
class node_db,node_models,node_config,node_age_gate toneRose
```

## Components

### Client apps

- [Mobile app](https://github.com/maanavar/sanstro/tree/main/mobile/app): `mobile/app`
- [Web app](https://github.com/maanavar/sanstro/tree/main/web/app): `web/app`
- [Shared API package](https://github.com/maanavar/sanstro/tree/main/packages/shared/src/api): `packages/shared/src/api`

### API and identity

- [FastAPI app](https://github.com/maanavar/sanstro/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/maanavar/sanstro/blob/main/app/api/auth.py): `app/api/auth.py`
- [Birth profiles](https://github.com/maanavar/sanstro/blob/main/app/api/birth_profiles.py): `app/api/birth_profiles.py`
- [Chart endpoints](https://github.com/maanavar/sanstro/blob/main/app/api/charts.py): `app/api/charts.py`
- [Public tools](https://github.com/maanavar/sanstro/blob/main/app/api/public_tools.py): `app/api/public_tools.py`

### Astrology and guidance

- [Chart calculations](https://github.com/maanavar/sanstro/blob/main/app/calculations/astro.py): `app/calculations/astro.py`
- [Chart strength](https://github.com/maanavar/sanstro/blob/main/app/calculations/chart_strength.py): `app/calculations/chart_strength.py`
- [Astrology display names](https://github.com/maanavar/sanstro/blob/main/app/calculations/display_names.py): `app/calculations/display_names.py`
- [Narrative guidance](https://github.com/maanavar/sanstro/blob/main/app/services/narrative_engine.py): `app/services/narrative_engine.py`
- [Daily guidance](https://github.com/maanavar/sanstro/blob/main/app/services/daily_guidance_service.py): `app/services/daily_guidance_service.py`
- [Panchangam](https://github.com/maanavar/sanstro/blob/main/app/calculations/panchangam.py): `app/calculations/panchangam.py`
- [Transits](https://github.com/maanavar/sanstro/blob/main/app/calculations/transits.py): `app/calculations/transits.py`
- [Muhurta](https://github.com/maanavar/sanstro/blob/main/app/calculations/muhurta_engine.py): `app/calculations/muhurta_engine.py`
- [Numerology](https://github.com/maanavar/sanstro/blob/main/app/calculations/numerology.py): `app/calculations/numerology.py`

### Data and operations

- [Database sessions](https://github.com/maanavar/sanstro/blob/main/app/db/session.py): `app/db/session.py`
- [Domain records](https://github.com/maanavar/sanstro/tree/main/app/models): `app/models`
- [Configuration](https://github.com/maanavar/sanstro/blob/main/app/core/config.py): `app/core/config.py`
- [Age gate](https://github.com/maanavar/sanstro/blob/main/app/core/age_gate.py): `app/core/age_gate.py`

### Other components

- **User**

## Connections

- User → Mobile app: uses (evidence: `README.md`)
- User → Web app: uses (evidence: `README.md`)
- Mobile app → Shared API package: uses API
- Web app → FastAPI app: proxies requests (evidence: `README.md`)
- Mobile app → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Authentication: registers routes (evidence: `app/main.py`)
- FastAPI app → Birth profiles: registers routes (evidence: `app/main.py`)
- FastAPI app → Chart endpoints: registers routes (evidence: `app/main.py`)
- FastAPI app → Public tools: registers routes (evidence: `app/main.py`)
- Authentication → Database sessions: opens session (evidence: `app/api/auth.py`)
- Birth profiles → Database sessions: opens session (evidence: `app/api/birth_profiles.py`)
- Chart endpoints → Chart calculations: uses calculations (evidence: `app/api/charts.py`)
- Chart endpoints → Chart strength: uses calculations (evidence: `app/api/charts.py`)
- Narrative guidance → Chart calculations: uses calculations (evidence: `app/services/narrative_engine.py`)
- Narrative guidance → Chart strength: uses calculations (evidence: `app/services/narrative_engine.py`)
- Narrative guidance → Astrology display names: uses labels (evidence: `app/services/narrative_engine.py`)
- Public tools → Muhurta: exposes tool
- Public tools → Panchangam: exposes tool
- Public tools → Numerology: exposes tool
- Database sessions → Configuration: reads settings (evidence: `app/db/session.py`)
- Database sessions → Domain records: persists records (evidence: `app/models/__init__.py`)
- Chart endpoints → Age gate: checks access (evidence: `app/api/charts.py`)
- Public tools → Transits: offers astrology
- Daily guidance → Narrative guidance: builds guidance
