# rebots-online/natally architecture

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

- Interactive diagram: https://gitdiagram.com/rebots-online/natally
- Repository: https://github.com/rebots-online/natally

## Overview

natally is a natal-astrology and synastry companion: a person provides birth details, receives chart-based conversation, and can view charts while the companion speaks. The local edition is the primary Android-targeted product, with a browser/PWA harness; a separate hosted edition is also in scope. The README documents charting, memory, model delivery, voice, and access capabilities, but marks much of the end-to-end integration partial or pending. The graph reflects documented capabilities and sampled runtime seams; unsampled implementation wiring is intentionally limited.

Main entry points: [`apps/local/src/composition.ts`](https://github.com/rebots-online/natally/blob/master/apps/local/src/composition.ts) (Conversation composition), [`apps/local/src/screens/conversation/route.tsx`](https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/conversation/route.tsx) (Conversation route), [`packages/ephemeris/src/seam.ts`](https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/seam.ts) (Ephemeris seam), [`apps/local/src/app.tsx`](https://github.com/rebots-online/natally/blob/master/apps/local/src/app.tsx) (Local app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Companion experience"]
  node_local_app["Local app<br/>[app.tsx]"]
  node_conversation["Conversation route<br/>[route.tsx]"]
  node_composition["Conversation composition<br/>[composition.ts]"]
  node_conversation_screen["Conversation screen"]
  node_onboarding["Onboarding<br/>[Splash.tsx]"]
  node_voice["Voice<br/>[web.ts]"]
end

subgraph group_astro["Astrology"]
  node_ephemeris["Ephemeris seam<br/>[seam.ts]"]
  node_sweph["Swiss Ephemeris<br/>[engine.ts]"]
  node_chart_facts["Chart facts<br/>[facts.ts]"]
end

subgraph group_memory["Memory and data"]
  node_lore_pipeline["Lore pipeline<br/>[pipeline.ts]"]
  node_lore_store["Lore store<br/>[store.ts]"]
  node_app_data["People and sessions<br/>[index.ts]"]
end

subgraph group_runtime["Local runtime"]
  node_model_mirror["Model catalogue and downloads<br/>[catalogue.ts]"]
  node_local_inference["Local inference<br/>[mod.rs]"]
end

subgraph group_access["Hosted and access"]
  node_hosted_app["Hosted edition<br/>[app.tsx]"]
  node_hosted_seams["Hosted service seams<br/>[seams.ts]"]
  node_billing["Billing contracts<br/>[ledger.ts]"]
  node_license_bridge["License bridge<br/>[main.rs]"]
end

node_person(("Person"))
node_external_inference(("Hosted inference provider"))

node_person -->|"opens"| node_local_app
node_local_app -->|"routes to"| node_conversation
node_conversation -->|"creates"| node_composition
node_conversation -->|"renders"| node_conversation_screen
node_person -->|"provides birth details"| node_conversation
node_person -->|"completes"| node_onboarding
node_composition -.->|"uses"| node_app_data
node_composition -.->|"uses"| node_local_inference
node_composition -.->|"uses"| node_model_mirror
node_conversation_screen -.->|"plays speech"| node_voice
node_ephemeris -->|"implements"| node_sweph
node_ephemeris -.->|"builds"| node_chart_facts
node_lore_pipeline -->|"flushes graph"| node_lore_store
node_hosted_app -->|"imports contracts"| node_hosted_seams
node_hosted_seams -.->|"awaits implementation"| node_external_inference
node_billing -.->|"verifies access"| node_license_bridge

click node_local_app "https://github.com/rebots-online/natally/blob/master/apps/local/src/app.tsx"
click node_conversation "https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/conversation/route.tsx"
click node_composition "https://github.com/rebots-online/natally/blob/master/apps/local/src/composition.ts"
click node_conversation_screen "https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/conversation/ConversationScreen.tsx"
click node_onboarding "https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/splash/Splash.tsx"
click node_voice "https://github.com/rebots-online/natally/blob/master/apps/local/src/voice/web.ts"
click node_ephemeris "https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/seam.ts"
click node_sweph "https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/sweph/engine.ts"
click node_chart_facts "https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/facts.ts"
click node_lore_pipeline "https://github.com/rebots-online/natally/blob/master/packages/lore/src/pipeline.ts"
click node_lore_store "https://github.com/rebots-online/natally/blob/master/packages/lore/src/store.ts"
click node_app_data "https://github.com/rebots-online/natally/blob/master/apps/local/src/data/index.ts"
click node_model_mirror "https://github.com/rebots-online/natally/blob/master/apps/local/src/mirror/catalogue.ts"
click node_local_inference "https://github.com/rebots-online/natally/blob/master/apps/local/src-tauri/src/inference/mod.rs"
click node_hosted_app "https://github.com/rebots-online/natally/blob/master/apps/hosted/src/app.tsx"
click node_hosted_seams "https://github.com/rebots-online/natally/blob/master/apps/hosted/src/seams.ts"
click node_billing "https://github.com/rebots-online/natally/blob/master/packages/billing/src/ledger.ts"
click node_license_bridge "https://github.com/rebots-online/natally/blob/master/services/license-bridge/src/main.rs"

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_local_app,node_conversation,node_composition,node_conversation_screen,node_onboarding,node_voice toneBlue
class node_ephemeris,node_sweph,node_chart_facts toneAmber
class node_lore_pipeline,node_lore_store,node_app_data toneMint
class node_model_mirror,node_local_inference toneRose
class node_hosted_app,node_hosted_seams,node_billing,node_license_bridge,node_person,node_external_inference toneIndigo
```

## Components

### Companion experience

- [Local app](https://github.com/rebots-online/natally/blob/master/apps/local/src/app.tsx): `apps/local/src/app.tsx`
- [Conversation route](https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/conversation/route.tsx): `apps/local/src/screens/conversation/route.tsx`
- [Conversation composition](https://github.com/rebots-online/natally/blob/master/apps/local/src/composition.ts): `apps/local/src/composition.ts`
- [Conversation screen](https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/conversation/ConversationScreen.tsx): `apps/local/src/screens/conversation/ConversationScreen.tsx`
- [Onboarding](https://github.com/rebots-online/natally/blob/master/apps/local/src/screens/splash/Splash.tsx): `apps/local/src/screens/splash/Splash.tsx`
- [Voice](https://github.com/rebots-online/natally/blob/master/apps/local/src/voice/web.ts): `apps/local/src/voice/web.ts`

### Astrology

- [Ephemeris seam](https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/seam.ts): `packages/ephemeris/src/seam.ts`
- [Swiss Ephemeris](https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/sweph/engine.ts): `packages/ephemeris/src/sweph/engine.ts`
- [Chart facts](https://github.com/rebots-online/natally/blob/master/packages/ephemeris/src/facts.ts): `packages/ephemeris/src/facts.ts`

### Memory and data

- [Lore pipeline](https://github.com/rebots-online/natally/blob/master/packages/lore/src/pipeline.ts): `packages/lore/src/pipeline.ts`
- [Lore store](https://github.com/rebots-online/natally/blob/master/packages/lore/src/store.ts): `packages/lore/src/store.ts`
- [People and sessions](https://github.com/rebots-online/natally/blob/master/apps/local/src/data/index.ts): `apps/local/src/data/index.ts`

### Local runtime

- [Model catalogue and downloads](https://github.com/rebots-online/natally/blob/master/apps/local/src/mirror/catalogue.ts): `apps/local/src/mirror/catalogue.ts`
- [Local inference](https://github.com/rebots-online/natally/blob/master/apps/local/src-tauri/src/inference/mod.rs): `apps/local/src-tauri/src/inference/mod.rs`

### Hosted and access

- [Hosted edition](https://github.com/rebots-online/natally/blob/master/apps/hosted/src/app.tsx): `apps/hosted/src/app.tsx`
- [Hosted service seams](https://github.com/rebots-online/natally/blob/master/apps/hosted/src/seams.ts): `apps/hosted/src/seams.ts`
- [Billing contracts](https://github.com/rebots-online/natally/blob/master/packages/billing/src/ledger.ts): `packages/billing/src/ledger.ts`
- [License bridge](https://github.com/rebots-online/natally/blob/master/services/license-bridge/src/main.rs): `services/license-bridge/src/main.rs`

### Other components

- **Person**
- **Hosted inference provider**

## Connections

- Person → Local app: opens
- Local app → Conversation route: routes to
- Conversation route → Conversation composition: creates
- Conversation route → Conversation screen: renders
- Person → Conversation route: provides birth details
- Person → Onboarding: completes
- Conversation composition → People and sessions: uses
- Conversation composition → Local inference: uses
- Conversation composition → Model catalogue and downloads: uses
- Conversation screen → Voice: plays speech
- Ephemeris seam → Swiss Ephemeris: implements
- Ephemeris seam → Chart facts: builds
- Lore pipeline → Lore store: flushes graph
- Hosted edition → Hosted service seams: imports contracts
- Hosted service seams → Hosted inference provider: awaits implementation
- Billing contracts → License bridge: verifies access