# doosemavis/astro-clock architecture

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

- Interactive diagram: https://gitdiagram.com/doosemavis/astro-clock
- Repository: https://github.com/doosemavis/astro-clock

## Overview

Astro App provides living astrological charts across web and mobile: users enter birth details, view fixed natal and moving planetary positions, and explore other times or chart comparisons. The shared engine computes chart data; the mobile app also provides onboarding, accounts, themes, exports, and purchases. Web adds account and Stripe subscription routes, while a RevenueCat webhook maps purchase events to subscription rows. The README documents the web MVP and engine; mobile relationships below are limited to indexed imports and excerpted calls.

Main entry points: [`apps/mobile/App.tsx`](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/App.tsx) (Mobile app shell), [`packages/engine/src/chart.ts`](https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/chart.ts) (Chart calculations), [`apps/mobile/components/BirthForm.tsx`](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/BirthForm.tsx) (Birth form), [`apps/mobile/components/auth/LoginScreen.tsx`](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/auth/LoginScreen.tsx) (Mobile login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Birth and onboarding"]
  node_birth["Birth form<br/>[BirthForm.tsx]"]
  node_birthdata["Birth data helpers<br/>[birthValidation.ts]"]
  node_places["Place lookup<br/>[geocode.ts]"]
end

subgraph group_charts["Chart experience"]
  node_mobile["Mobile app shell<br/>[App.tsx]"]
  node_clock["Chart time control<br/>[useChartClock.ts]"]
  node_controls["Chart controls<br/>[ChartControls.tsx]"]
  node_wheel["Chart wheel<br/>[ChartWheel.tsx]"]
  node_compare["Chart comparison<br/>[CompareView.tsx]"]
  node_sky["Sky backdrop<br/>[Sky.tsx]"]
  node_coordinates["Coordinate readings"]
  node_export["Chart export<br/>[ExportCard.tsx]"]
end

subgraph group_core["Astrology and readings"]
  node_engine["Chart calculations<br/>[chart.ts]"]
  node_ephemeris["Planet positions<br/>[ephemeris.ts]"]
  node_aspects["Planet aspects<br/>[aspects.ts]"]
  node_interpret["Interpretations<br/>[assemble.ts]"]
end

subgraph group_identity["Accounts and access"]
  node_auth["Mobile authentication<br/>[auth.tsx]"]
  node_login["Mobile login<br/>[LoginScreen.tsx]"]
end

subgraph group_services["Persistence and billing"]
  node_subscriptions["Subscription routes<br/>[route.ts]"]
  node_stripe["Stripe"]
  node_rcwebhook["RevenueCat webhook<br/>[index.ts]"]
  node_subscriptionrow["Subscription event mapper<br/>[rcEventToRow.ts]"]
  node_store[("Supabase data<br/>[server.ts]")]
end

node_person(("Chart user"))

node_person -->|"opens"| node_mobile
node_mobile -->|"opens form"| node_birth
node_birth -->|"searches places"| node_places
node_birth -->|"submits details"| node_mobile
node_mobile -.->|"sets chart time"| node_clock
node_mobile -.->|"shows controls"| node_controls
node_mobile -->|"renders chart"| node_wheel
node_mobile -->|"renders comparison"| node_compare
node_mobile -->|"renders backdrop"| node_sky
node_mobile -->|"opens readings"| node_coordinates
node_mobile -->|"exports chart"| node_export
node_clock -.->|"resolves positions"| node_engine
node_wheel -.->|"displays chart data"| node_engine
node_engine -->|"uses positions"| node_ephemeris
node_engine -->|"computes aspects"| node_aspects
node_engine -.->|"supplies chart data"| node_interpret
node_person -->|"requests account"| node_login
node_mobile -.->|"opens sign-in"| node_login
node_login -->|"authenticates"| node_auth
node_person -->|"manages plan"| node_subscriptions
node_subscriptions -->|"creates checkout"| node_stripe
node_rcwebhook -->|"maps event"| node_subscriptionrow
node_subscriptionrow -.->|"writes subscription"| node_store

click node_mobile "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/App.tsx"
click node_birth "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/BirthForm.tsx"
click node_birthdata "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/lib/birthValidation.ts"
click node_places "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/lib/geocode.ts"
click node_clock "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/hooks/useChartClock.ts"
click node_controls "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/ChartControls.tsx"
click node_wheel "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/ChartWheel.tsx"
click node_compare "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/CompareView.tsx"
click node_sky "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/Sky.tsx"
click node_coordinates "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/coordinates/CoordinatesPanel.tsx"
click node_export "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/export/ExportCard.tsx"
click node_engine "https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/chart.ts"
click node_ephemeris "https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/ephemeris.ts"
click node_aspects "https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/aspects.ts"
click node_interpret "https://github.com/doosemavis/astro-clock/blob/main/packages/interpretations/src/assemble.ts"
click node_auth "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/lib/auth.tsx"
click node_login "https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/auth/LoginScreen.tsx"
click node_subscriptions "https://github.com/doosemavis/astro-clock/blob/main/apps/web/app/api/stripe/checkout/route.ts"
click node_rcwebhook "https://github.com/doosemavis/astro-clock/blob/main/supabase/functions/revenuecat-webhook/index.ts"
click node_subscriptionrow "https://github.com/doosemavis/astro-clock/blob/main/supabase/functions/_shared/rcEventToRow.ts"
click node_store "https://github.com/doosemavis/astro-clock/blob/main/apps/web/lib/supabase/server.ts"

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_birth,node_birthdata,node_places,node_person toneBlue
class node_mobile,node_clock,node_controls,node_wheel,node_compare,node_sky,node_coordinates,node_export toneAmber
class node_engine,node_ephemeris,node_aspects,node_interpret toneMint
class node_auth,node_login toneRose
class node_subscriptions,node_stripe,node_rcwebhook,node_subscriptionrow,node_store toneIndigo
```

## Components

### Birth and onboarding

- [Birth form](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/BirthForm.tsx): `apps/mobile/components/BirthForm.tsx`
- [Birth data helpers](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/lib/birthValidation.ts): `apps/mobile/lib/birthValidation.ts`
- [Place lookup](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/lib/geocode.ts): `apps/mobile/lib/geocode.ts`

### Chart experience

- [Mobile app shell](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/App.tsx): `apps/mobile/App.tsx`
- [Chart time control](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/hooks/useChartClock.ts): `apps/mobile/hooks/useChartClock.ts`
- [Chart controls](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/ChartControls.tsx): `apps/mobile/components/chart/ChartControls.tsx`
- [Chart wheel](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/ChartWheel.tsx): `apps/mobile/components/chart/ChartWheel.tsx`
- [Chart comparison](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/CompareView.tsx): `apps/mobile/components/chart/CompareView.tsx`
- [Sky backdrop](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/chart/Sky.tsx): `apps/mobile/components/chart/Sky.tsx`
- [Coordinate readings](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/coordinates/CoordinatesPanel.tsx): `apps/mobile/components/coordinates/CoordinatesPanel.tsx`
- [Chart export](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/export/ExportCard.tsx): `apps/mobile/components/export/ExportCard.tsx`

### Astrology and readings

- [Chart calculations](https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/chart.ts): `packages/engine/src/chart.ts`
- [Planet positions](https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/ephemeris.ts): `packages/engine/src/ephemeris.ts`
- [Planet aspects](https://github.com/doosemavis/astro-clock/blob/main/packages/engine/src/aspects.ts): `packages/engine/src/aspects.ts`
- [Interpretations](https://github.com/doosemavis/astro-clock/blob/main/packages/interpretations/src/assemble.ts): `packages/interpretations/src/assemble.ts`

### Accounts and access

- [Mobile authentication](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/lib/auth.tsx): `apps/mobile/lib/auth.tsx`
- [Mobile login](https://github.com/doosemavis/astro-clock/blob/main/apps/mobile/components/auth/LoginScreen.tsx): `apps/mobile/components/auth/LoginScreen.tsx`

### Persistence and billing

- [Subscription routes](https://github.com/doosemavis/astro-clock/blob/main/apps/web/app/api/stripe/checkout/route.ts): `apps/web/app/api/stripe/checkout/route.ts`
- **Stripe**
- [RevenueCat webhook](https://github.com/doosemavis/astro-clock/blob/main/supabase/functions/revenuecat-webhook/index.ts): `supabase/functions/revenuecat-webhook/index.ts`
- [Subscription event mapper](https://github.com/doosemavis/astro-clock/blob/main/supabase/functions/_shared/rcEventToRow.ts): `supabase/functions/_shared/rcEventToRow.ts`
- [Supabase data](https://github.com/doosemavis/astro-clock/blob/main/apps/web/lib/supabase/server.ts): `apps/web/lib/supabase/server.ts`

### Other components

- **Chart user**

## Connections

- Chart user → Mobile app shell: opens
- Mobile app shell → Birth form: opens form (evidence: `apps/mobile/App.tsx`)
- Birth form → Place lookup: searches places (evidence: `apps/mobile/components/BirthForm.tsx`)
- Birth form → Mobile app shell: submits details (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Chart time control: sets chart time (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Chart controls: shows controls (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Chart wheel: renders chart (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Chart comparison: renders comparison (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Sky backdrop: renders backdrop (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Coordinate readings: opens readings (evidence: `apps/mobile/App.tsx`)
- Mobile app shell → Chart export: exports chart (evidence: `apps/mobile/App.tsx`)
- Chart time control → Chart calculations: resolves positions
- Chart wheel → Chart calculations: displays chart data
- Chart calculations → Planet positions: uses positions
- Chart calculations → Planet aspects: computes aspects
- Chart calculations → Interpretations: supplies chart data
- Chart user → Mobile login: requests account
- Mobile app shell → Mobile login: opens sign-in (evidence: `apps/mobile/App.tsx`)
- Mobile login → Mobile authentication: authenticates (evidence: `apps/mobile/components/auth/LoginScreen.tsx`)
- Chart user → Subscription routes: manages plan
- Subscription routes → Stripe: creates checkout
- RevenueCat webhook → Subscription event mapper: maps event (evidence: `supabase/functions/revenuecat-webhook/index.ts`)
- Subscription event mapper → Supabase data: writes subscription
