# farnai/jester architecture

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

- Interactive diagram: https://gitdiagram.com/farnai/jester
- Repository: https://github.com/farnai/jester

## Overview

JESTER is a people-discovery and relationship-intelligence product: users register and provide birth/profile details, discover people, inspect compatibility, and continue through connections and messaging. Its backend calculates private natal astrology, derives deterministic synastry, and resolves signals into contextual interpretation; discovery itself is documented as bounded and does not recalculate astrology. The graph combines sampled call/import evidence with README-documented capabilities. Unsampled feature implementations are represented at supported directory paths; their internal call wiring is not inferred.

Main entry points: [`backend/app/comparisons/router.py`](https://github.com/farnai/jester/blob/main/backend/app/comparisons/router.py) (Comparison API), [`backend/app/api/router.py`](https://github.com/farnai/jester/blob/main/backend/app/api/router.py) (API router), [`frontend/src/core/api/client.ts`](https://github.com/farnai/jester/blob/main/frontend/src/core/api/client.ts) (API client), [`frontend/src/navigation/AppRoutes.tsx`](https://github.com/farnai/jester/blob/main/frontend/src/navigation/AppRoutes.tsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_routes["App routes<br/>[AppRoutes.tsx]"]
  node_authui["Auth screens"]
  node_onboarding["Birth onboarding"]
  node_clientapi["API client<br/>[client.ts]"]
  node_discoverui["Discover people"]
  node_compareui["Compatibility views"]
  node_socialui["Social surfaces"]
  node_chatui["Messages and chat"]
end

subgraph group_identity["Identity and profiles"]
  node_authbackend["JWT identity<br/>[dependencies.py]"]
  node_profiles["Profiles and photos<br/>[router.py]"]
  node_geo["Canonical locations<br/>[service.py]"]
end

subgraph group_intelligence["Astrology and interpretation"]
  node_natal["Natal astrology<br/>[natal.py]"]
  node_compatibility["Synastry scoring<br/>[engine.py]"]
  node_interpretation["Interpretation engine<br/>[engine.py]"]
  node_content["Georgian content<br/>[library.py]"]
end

subgraph group_social["Discovery and relationships"]
  node_discovery["Discovery API<br/>[router.py]"]
  node_comparisons["Comparison API<br/>[router.py]"]
  node_connections["Connection states<br/>[router.py]"]
  node_conversations["Conversations<br/>[router.py]"]
end

subgraph group_platform["API and persistence"]
  node_api["API router<br/>[router.py]"]
  node_database[("PostgreSQL / Supabase<br/>[database.py]")]
end

node_person(("Person"))
node_supabaseauth["Supabase Auth"]

node_person -->|"uses"| node_routes
node_routes -->|"routes to"| node_authui
node_routes -->|"routes to"| node_onboarding
node_routes -->|"routes to"| node_discoverui
node_routes -->|"routes to"| node_compareui
node_person -->|"registers"| node_authui
node_authui -->|"authenticates"| node_supabaseauth
node_onboarding -.->|"submits details"| node_clientapi
node_discoverui -.->|"requests people"| node_clientapi
node_compareui -.->|"requests comparison"| node_clientapi
node_socialui -.->|"uses API"| node_clientapi
node_chatui -.->|"uses API"| node_clientapi
node_clientapi -->|"calls API"| node_api
node_api -->|"registers"| node_discovery
node_api -->|"registers"| node_comparisons
node_api -->|"registers"| node_profiles
node_api -->|"registers"| node_connections
node_api -->|"registers"| node_conversations
node_supabaseauth -->|"issues JWT"| node_authbackend
node_profiles -->|"depends on"| node_authbackend
node_profiles -->|"uses locations"| node_geo
node_discovery -->|"depends on"| node_authbackend
node_discovery -->|"queries profiles"| node_database
node_comparisons -->|"depends on"| node_authbackend
node_comparisons -->|"reads and writes"| node_database
node_comparisons -->|"recalculates charts"| node_natal
node_comparisons -->|"calculates synastry"| node_compatibility
node_compatibility -->|"provides signals"| node_interpretation
node_comparisons -->|"resolves analysis"| node_interpretation
node_interpretation -->|"resolves copy"| node_content
node_natal -->|"stores private chart"| node_database
node_connections -->|"stores states"| node_database
node_conversations -->|"stores messages"| node_database
node_discoverui -.->|"opens profiles"| node_socialui
node_compareui -.->|"invites connection"| node_socialui

click node_routes "https://github.com/farnai/jester/blob/main/frontend/src/navigation/AppRoutes.tsx"
click node_authui "https://github.com/farnai/jester/tree/main/frontend/src/modules/auth"
click node_onboarding "https://github.com/farnai/jester/tree/main/frontend/src/modules/onboarding"
click node_clientapi "https://github.com/farnai/jester/blob/main/frontend/src/core/api/client.ts"
click node_discoverui "https://github.com/farnai/jester/tree/main/frontend/src/modules/discover"
click node_compareui "https://github.com/farnai/jester/tree/main/frontend/src/modules/compatibility"
click node_socialui "https://github.com/farnai/jester/tree/main/frontend/src/modules/connections"
click node_chatui "https://github.com/farnai/jester/tree/main/frontend/src/modules/messages"
click node_authbackend "https://github.com/farnai/jester/blob/main/backend/app/auth/dependencies.py"
click node_profiles "https://github.com/farnai/jester/blob/main/backend/app/profiles/router.py"
click node_geo "https://github.com/farnai/jester/blob/main/backend/app/geo/service.py"
click node_natal "https://github.com/farnai/jester/blob/main/backend/app/astrology/natal.py"
click node_compatibility "https://github.com/farnai/jester/blob/main/backend/app/compatibility/engine.py"
click node_interpretation "https://github.com/farnai/jester/blob/main/backend/app/interpretation/engine.py"
click node_content "https://github.com/farnai/jester/blob/main/backend/app/interpretation/library.py"
click node_discovery "https://github.com/farnai/jester/blob/main/backend/app/discovery/router.py"
click node_comparisons "https://github.com/farnai/jester/blob/main/backend/app/comparisons/router.py"
click node_connections "https://github.com/farnai/jester/blob/main/backend/app/connections/router.py"
click node_conversations "https://github.com/farnai/jester/blob/main/backend/app/conversations/router.py"
click node_api "https://github.com/farnai/jester/blob/main/backend/app/api/router.py"
click node_database "https://github.com/farnai/jester/blob/main/backend/app/core/database.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_routes,node_authui,node_onboarding,node_clientapi,node_discoverui,node_compareui,node_socialui,node_chatui toneBlue
class node_authbackend,node_profiles,node_geo toneAmber
class node_natal,node_compatibility,node_interpretation,node_content toneMint
class node_discovery,node_comparisons,node_connections,node_conversations toneRose
class node_api,node_database,node_person,node_supabaseauth toneIndigo
```

## Components

### Web client

- [App routes](https://github.com/farnai/jester/blob/main/frontend/src/navigation/AppRoutes.tsx): `frontend/src/navigation/AppRoutes.tsx`
- [Auth screens](https://github.com/farnai/jester/tree/main/frontend/src/modules/auth): `frontend/src/modules/auth`
- [Birth onboarding](https://github.com/farnai/jester/tree/main/frontend/src/modules/onboarding): `frontend/src/modules/onboarding`
- [API client](https://github.com/farnai/jester/blob/main/frontend/src/core/api/client.ts): `frontend/src/core/api/client.ts`
- [Discover people](https://github.com/farnai/jester/tree/main/frontend/src/modules/discover): `frontend/src/modules/discover`
- [Compatibility views](https://github.com/farnai/jester/tree/main/frontend/src/modules/compatibility): `frontend/src/modules/compatibility`
- [Social surfaces](https://github.com/farnai/jester/tree/main/frontend/src/modules/connections): `frontend/src/modules/connections`
- [Messages and chat](https://github.com/farnai/jester/tree/main/frontend/src/modules/messages): `frontend/src/modules/messages`

### Identity and profiles

- [JWT identity](https://github.com/farnai/jester/blob/main/backend/app/auth/dependencies.py): `backend/app/auth/dependencies.py`
- [Profiles and photos](https://github.com/farnai/jester/blob/main/backend/app/profiles/router.py): `backend/app/profiles/router.py`
- [Canonical locations](https://github.com/farnai/jester/blob/main/backend/app/geo/service.py): `backend/app/geo/service.py`

### Astrology and interpretation

- [Natal astrology](https://github.com/farnai/jester/blob/main/backend/app/astrology/natal.py): `backend/app/astrology/natal.py`
- [Synastry scoring](https://github.com/farnai/jester/blob/main/backend/app/compatibility/engine.py): `backend/app/compatibility/engine.py`
- [Interpretation engine](https://github.com/farnai/jester/blob/main/backend/app/interpretation/engine.py): `backend/app/interpretation/engine.py`
- [Georgian content](https://github.com/farnai/jester/blob/main/backend/app/interpretation/library.py): `backend/app/interpretation/library.py`

### Discovery and relationships

- [Discovery API](https://github.com/farnai/jester/blob/main/backend/app/discovery/router.py): `backend/app/discovery/router.py`
- [Comparison API](https://github.com/farnai/jester/blob/main/backend/app/comparisons/router.py): `backend/app/comparisons/router.py`
- [Connection states](https://github.com/farnai/jester/blob/main/backend/app/connections/router.py): `backend/app/connections/router.py`
- [Conversations](https://github.com/farnai/jester/blob/main/backend/app/conversations/router.py): `backend/app/conversations/router.py`

### API and persistence

- [API router](https://github.com/farnai/jester/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [PostgreSQL / Supabase](https://github.com/farnai/jester/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Person**
- **Supabase Auth**

## Connections

- Person → App routes: uses (evidence: `README.md`)
- App routes → Auth screens: routes to (evidence: `frontend/src/navigation/AppRoutes.tsx`)
- App routes → Birth onboarding: routes to (evidence: `frontend/src/navigation/AppRoutes.tsx`)
- App routes → Discover people: routes to (evidence: `frontend/src/navigation/AppRoutes.tsx`)
- App routes → Compatibility views: routes to (evidence: `frontend/src/navigation/AppRoutes.tsx`)
- Person → Auth screens: registers (evidence: `README.md`)
- Auth screens → Supabase Auth: authenticates (evidence: `README.md`)
- Birth onboarding → API client: submits details
- Discover people → API client: requests people
- Compatibility views → API client: requests comparison
- Social surfaces → API client: uses API
- Messages and chat → API client: uses API
- API client → API router: calls API (evidence: `README.md`)
- API router → Discovery API: registers (evidence: `backend/app/api/router.py`)
- API router → Comparison API: registers (evidence: `backend/app/api/router.py`)
- API router → Profiles and photos: registers (evidence: `backend/app/api/router.py`)
- API router → Connection states: registers (evidence: `backend/app/api/router.py`)
- API router → Conversations: registers (evidence: `backend/app/api/router.py`)
- Supabase Auth → JWT identity: issues JWT (evidence: `README.md`)
- Profiles and photos → JWT identity: depends on (evidence: `backend/app/profiles/router.py`)
- Profiles and photos → Canonical locations: uses locations (evidence: `backend/app/profiles/router.py`)
- Discovery API → JWT identity: depends on (evidence: `backend/app/discovery/router.py`)
- Discovery API → PostgreSQL / Supabase: queries profiles (evidence: `backend/app/discovery/router.py`)
- Comparison API → JWT identity: depends on (evidence: `backend/app/comparisons/router.py`)
- Comparison API → PostgreSQL / Supabase: reads and writes (evidence: `backend/app/comparisons/router.py`)
- Comparison API → Natal astrology: recalculates charts (evidence: `backend/app/comparisons/router.py`)
- Comparison API → Synastry scoring: calculates synastry (evidence: `backend/app/comparisons/router.py`)
- Synastry scoring → Interpretation engine: provides signals (evidence: `README.md`)
- Comparison API → Interpretation engine: resolves analysis (evidence: `backend/app/comparisons/router.py`)
- Interpretation engine → Georgian content: resolves copy (evidence: `backend/app/interpretation/engine.py`)
- Natal astrology → PostgreSQL / Supabase: stores private chart (evidence: `README.md`)
- Connection states → PostgreSQL / Supabase: stores states (evidence: `README.md`)
- Conversations → PostgreSQL / Supabase: stores messages (evidence: `README.md`)
- Discover people → Social surfaces: opens profiles
- Compatibility views → Social surfaces: invites connection
