# satyaa133/electa architecture

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

- Interactive diagram: https://gitdiagram.com/satyaa133/electa
- Repository: https://github.com/satyaa133/electa

## Overview

Electa is a mood- and location-aware discovery app: users choose a mood and category, receive tailored recommendations, inspect details, and ask follow-up questions; account holders can save items and synchronize preferences. The React app calls an Express API, which generates recommendations with Gemini and supports accounts, location, and user data. README capabilities such as browser caching, Neon caching, and probabilistic freshness are included as documented but unsampled; their internal links are therefore not asserted. API middleware and cache wiring beyond shown imports and excerpts are not expanded.

Main entry points: [`src/App.tsx`](https://github.com/satyaa133/electa/blob/main/src/App.tsx) (App coordinator), [`api/index.ts`](https://github.com/satyaa133/electa/blob/main/api/index.ts) (Express API), [`src/services/gemini.ts`](https://github.com/satyaa133/electa/blob/main/src/services/gemini.ts) (Recommendation client), [`src/components/ChatModal.tsx`](https://github.com/satyaa133/electa/blob/main/src/components/ChatModal.tsx) (Follow-up chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery experience"]
  node_app["App coordinator<br/>[App.tsx]"]
  node_mood["Mood selection<br/>[MoodSection.tsx]"]
  node_category["Category selection"]
  node_recommendations["Recommendation grid"]
  node_recommendation_api["Recommendation client<br/>[gemini.ts]"]
  node_detail["Recommendation details<br/>[DetailModal.tsx]"]
  node_chat["Follow-up chat<br/>[ChatModal.tsx]"]
  node_location_ui["Location controls<br/>[LocationModal.tsx]"]
  node_landing["Landing experience<br/>[LandingPage.tsx]"]
end

subgraph group_account["Accounts and profile"]
  node_auth_ui["Sign-in and signup<br/>[AuthPage.tsx]"]
  node_profile["Profile and bookmarks<br/>[ProfileModal.tsx]"]
end

subgraph group_backend["API and recommendation engine"]
  node_cache[("Dual-layer cache")]
  node_api["Express API<br/>[index.ts]"]
  node_gemini["Gemini generation<br/>[index.ts]"]
  node_key_rotation["API key rotation<br/>[apiKeyManager.ts]"]
  node_neon[("Neon PostgreSQL")]
  node_location_service["IP location lookup<br/>[index.ts]"]
  node_weather["Weather context<br/>[index.ts]"]
end

subgraph group_controls["API security"]
  node_auth_middleware["Auth middleware<br/>[authMiddleware.ts]"]
  node_sessions["Session tokens<br/>[sessionManager.ts]"]
  node_security_middleware["Request protections<br/>[cors.ts]"]
end

node_user(("Discoverer"))
node_google["Google Gemini"]
node_ip_services["IP location providers"]
node_weather_service["wttr.in"]
node_browser[("Browser storage")]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_mood
node_app -->|"renders"| node_category
node_app -->|"renders"| node_recommendations
node_app -->|"requests recommendations"| node_recommendation_api
node_recommendation_api -->|"POSTs requests"| node_api
node_api -->|"generates recommendations"| node_gemini
node_gemini -.->|"uses keys"| node_key_rotation
node_gemini -->|"calls"| node_google
node_api -->|"handles location"| node_location_service
node_location_service -->|"queries"| node_ip_services
node_api -->|"fetches context"| node_weather
node_weather -->|"queries"| node_weather_service
node_app -->|"renders"| node_detail
node_app -->|"renders"| node_chat
node_app -->|"submits questions"| node_chat
node_chat -->|"requests answers"| node_recommendation_api
node_recommendation_api -->|"POSTs questions"| node_api
node_app -->|"renders"| node_location_ui
node_app -->|"renders"| node_landing
node_app -->|"renders"| node_auth_ui
node_app -->|"renders"| node_profile
node_auth_ui -.->|"calls auth endpoints"| node_api
node_profile -.->|"syncs profile"| node_api
node_api -->|"protects routes"| node_auth_middleware
node_auth_middleware -->|"validates tokens"| node_sessions
node_api -.->|"reads and writes"| node_neon
node_app -.->|"uses cache"| node_cache
node_cache -.->|"persists cache"| node_neon
node_cache -.->|"stores locally"| node_browser
node_api -->|"configures protections"| node_security_middleware

click node_app "https://github.com/satyaa133/electa/blob/main/src/App.tsx"
click node_mood "https://github.com/satyaa133/electa/blob/main/src/components/MoodSection.tsx"
click node_category "https://github.com/satyaa133/electa/blob/main/src/components/CategorySection.tsx"
click node_recommendations "https://github.com/satyaa133/electa/blob/main/src/components/RecommendationsGrid.tsx"
click node_recommendation_api "https://github.com/satyaa133/electa/blob/main/src/services/gemini.ts"
click node_detail "https://github.com/satyaa133/electa/blob/main/src/components/DetailModal.tsx"
click node_chat "https://github.com/satyaa133/electa/blob/main/src/components/ChatModal.tsx"
click node_location_ui "https://github.com/satyaa133/electa/blob/main/src/components/LocationModal.tsx"
click node_landing "https://github.com/satyaa133/electa/blob/main/src/components/LandingPage.tsx"
click node_auth_ui "https://github.com/satyaa133/electa/blob/main/src/components/AuthPage.tsx"
click node_profile "https://github.com/satyaa133/electa/blob/main/src/components/ProfileModal.tsx"
click node_api "https://github.com/satyaa133/electa/blob/main/api/index.ts"
click node_gemini "https://github.com/satyaa133/electa/blob/main/api/index.ts"
click node_key_rotation "https://github.com/satyaa133/electa/blob/main/api/config/apiKeyManager.ts"
click node_location_service "https://github.com/satyaa133/electa/blob/main/api/index.ts"
click node_weather "https://github.com/satyaa133/electa/blob/main/api/index.ts"
click node_auth_middleware "https://github.com/satyaa133/electa/blob/main/api/middleware/authMiddleware.ts"
click node_sessions "https://github.com/satyaa133/electa/blob/main/api/auth/sessionManager.ts"
click node_security_middleware "https://github.com/satyaa133/electa/blob/main/api/middleware/cors.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_app,node_mood,node_category,node_recommendations,node_recommendation_api,node_detail,node_chat,node_location_ui,node_landing toneBlue
class node_auth_ui,node_profile,node_browser toneAmber
class node_cache,node_api,node_gemini,node_key_rotation,node_neon,node_location_service,node_weather toneMint
class node_auth_middleware,node_sessions,node_security_middleware toneRose
class node_user,node_google,node_ip_services,node_weather_service toneIndigo
```

## Components

### Discovery experience

- [App coordinator](https://github.com/satyaa133/electa/blob/main/src/App.tsx): `src/App.tsx`
- [Mood selection](https://github.com/satyaa133/electa/blob/main/src/components/MoodSection.tsx): `src/components/MoodSection.tsx`
- [Category selection](https://github.com/satyaa133/electa/blob/main/src/components/CategorySection.tsx): `src/components/CategorySection.tsx`
- [Recommendation grid](https://github.com/satyaa133/electa/blob/main/src/components/RecommendationsGrid.tsx): `src/components/RecommendationsGrid.tsx`
- [Recommendation client](https://github.com/satyaa133/electa/blob/main/src/services/gemini.ts): `src/services/gemini.ts`
- [Recommendation details](https://github.com/satyaa133/electa/blob/main/src/components/DetailModal.tsx): `src/components/DetailModal.tsx`
- [Follow-up chat](https://github.com/satyaa133/electa/blob/main/src/components/ChatModal.tsx): `src/components/ChatModal.tsx`
- [Location controls](https://github.com/satyaa133/electa/blob/main/src/components/LocationModal.tsx): `src/components/LocationModal.tsx`
- [Landing experience](https://github.com/satyaa133/electa/blob/main/src/components/LandingPage.tsx): `src/components/LandingPage.tsx`

### Accounts and profile

- [Sign-in and signup](https://github.com/satyaa133/electa/blob/main/src/components/AuthPage.tsx): `src/components/AuthPage.tsx`
- [Profile and bookmarks](https://github.com/satyaa133/electa/blob/main/src/components/ProfileModal.tsx): `src/components/ProfileModal.tsx`

### API and recommendation engine

- **Dual-layer cache**
- [Express API](https://github.com/satyaa133/electa/blob/main/api/index.ts): `api/index.ts`
- [Gemini generation](https://github.com/satyaa133/electa/blob/main/api/index.ts): `api/index.ts`
- [API key rotation](https://github.com/satyaa133/electa/blob/main/api/config/apiKeyManager.ts): `api/config/apiKeyManager.ts`
- **Neon PostgreSQL**
- [IP location lookup](https://github.com/satyaa133/electa/blob/main/api/index.ts): `api/index.ts`
- [Weather context](https://github.com/satyaa133/electa/blob/main/api/index.ts): `api/index.ts`

### API security

- [Auth middleware](https://github.com/satyaa133/electa/blob/main/api/middleware/authMiddleware.ts): `api/middleware/authMiddleware.ts`
- [Session tokens](https://github.com/satyaa133/electa/blob/main/api/auth/sessionManager.ts): `api/auth/sessionManager.ts`
- [Request protections](https://github.com/satyaa133/electa/blob/main/api/middleware/cors.ts): `api/middleware/cors.ts`

### Other components

- **Discoverer**
- **Google Gemini**
- **IP location providers**
- **wttr.in**
- **Browser storage**

## Connections

- Discoverer → App coordinator: uses (evidence: `README.md`)
- App coordinator → Mood selection: renders (evidence: `src/App.tsx`)
- App coordinator → Category selection: renders (evidence: `src/App.tsx`)
- App coordinator → Recommendation grid: renders (evidence: `src/App.tsx`)
- App coordinator → Recommendation client: requests recommendations (evidence: `src/services/gemini.ts`)
- Recommendation client → Express API: POSTs requests (evidence: `src/services/gemini.ts`)
- Express API → Gemini generation: generates recommendations (evidence: `api/index.ts`)
- Gemini generation → API key rotation: uses keys (evidence: `api/index.ts`)
- Gemini generation → Google Gemini: calls (evidence: `api/index.ts`)
- Express API → IP location lookup: handles location (evidence: `api/index.ts`)
- IP location lookup → IP location providers: queries (evidence: `api/index.ts`)
- Express API → Weather context: fetches context (evidence: `api/index.ts`)
- Weather context → wttr.in: queries (evidence: `api/index.ts`)
- App coordinator → Recommendation details: renders (evidence: `src/App.tsx`)
- App coordinator → Follow-up chat: renders (evidence: `src/App.tsx`)
- App coordinator → Follow-up chat: submits questions (evidence: `src/App.tsx`)
- Follow-up chat → Recommendation client: requests answers (evidence: `src/services/gemini.ts`)
- Recommendation client → Express API: POSTs questions (evidence: `src/services/gemini.ts`)
- App coordinator → Location controls: renders (evidence: `src/App.tsx`)
- App coordinator → Landing experience: renders (evidence: `src/App.tsx`)
- App coordinator → Sign-in and signup: renders (evidence: `src/App.tsx`)
- App coordinator → Profile and bookmarks: renders (evidence: `src/App.tsx`)
- Sign-in and signup → Express API: calls auth endpoints
- Profile and bookmarks → Express API: syncs profile
- Express API → Auth middleware: protects routes (evidence: `api/index.ts`)
- Auth middleware → Session tokens: validates tokens (evidence: `api/middleware/authMiddleware.ts`)
- Express API → Neon PostgreSQL: reads and writes (evidence: `README.md`)
- App coordinator → Dual-layer cache: uses cache (evidence: `README.md`)
- Dual-layer cache → Neon PostgreSQL: persists cache (evidence: `README.md`)
- Dual-layer cache → Browser storage: stores locally (evidence: `README.md`)
- Express API → Request protections: configures protections (evidence: `api/index.ts`)
