# lemon-2-ade/trove-backend architecture

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

- Interactive diagram: https://gitdiagram.com/lemon-2-ade/trove-backend
- Repository: https://github.com/lemon-2-ade/trove-backend

## Overview

SoloMate is a FastAPI backend for gamified solo travel: users authenticate, explore cities, take on quests, and manage trip, safety, and community features. The route tree documents these product areas; sampled source confirms application startup, database initialization, email/Google authentication, AI recommendations, and safety reporting. Other route capabilities are represented from their names, but their internal wiring is not established by the available excerpts.

Main entry points: [`main.py`](https://github.com/lemon-2-ade/trove-backend/blob/main/main.py) (FastAPI app), [`app/api/routes/auth.py`](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/auth.py) (Authentication), [`app/core/database.py`](https://github.com/lemon-2-ade/trove-backend/blob/main/app/core/database.py) (Prisma database), [`app/api/routes/ai_recommendations.py`](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/ai_recommendations.py) (AI recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry and identity"]
  node_main["FastAPI app<br/>[main.py]"]
  node_auth_route["Authentication<br/>[auth.py]"]
  node_users_route["User profiles<br/>[users.py]"]
  node_preferences_route["Preferences<br/>[preferences.py]"]
end

subgraph group_travel["Travel and exploration"]
  node_cities_route["Cities<br/>[cities.py]"]
  node_exploration_route["Place exploration<br/>[exploration.py]"]
  node_itinerary_route["Itineraries<br/>[itinerary.py]"]
  node_ai_route["AI recommendations"]
  node_journal_route["Travel journal<br/>[journal.py]"]
end

subgraph group_engagement["Gamification and community"]
  node_quests_route["Quests<br/>[quests.py]"]
  node_badges_route["Badges<br/>[badges.py]"]
  node_leaderboards_route["Leaderboards<br/>[leaderboards.py]"]
end

subgraph group_safety["Safety and assistance"]
  node_safety_route["Safety reports<br/>[safety.py]"]
  node_emergency_route["Emergency contacts"]
  node_news_service["News analysis"]
  node_scraping_service["News collection"]
end

subgraph group_platform["Core services"]
  node_auth_service["Token and passwords<br/>[auth.py]"]
  node_oauth_service["Google OAuth<br/>[google_oauth.py]"]
  node_ai_service["Travel AI agent<br/>[ai_agent.py]"]
  node_maps_service["Maps integration<br/>[google_maps.py]"]
  node_database[("Prisma database<br/>[database.py]")]
end

node_traveler(("Traveler"))
node_google(("Google identity"))
node_openai(("OpenAI"))

node_traveler -->|"calls API"| node_main
node_main -->|"routes requests"| node_auth_route
node_main -->|"routes requests"| node_users_route
node_main -->|"routes requests"| node_preferences_route
node_main -->|"routes requests"| node_cities_route
node_main -->|"routes requests"| node_exploration_route
node_main -->|"routes requests"| node_itinerary_route
node_main -->|"routes requests"| node_quests_route
node_main -->|"routes requests"| node_badges_route
node_main -->|"routes requests"| node_leaderboards_route
node_main -->|"routes requests"| node_ai_route
node_main -->|"routes requests"| node_journal_route
node_main -->|"routes requests"| node_safety_route
node_main -->|"routes requests"| node_emergency_route
node_main -->|"initializes"| node_database
node_auth_route -->|"reads and writes"| node_database
node_auth_route -->|"creates tokens"| node_auth_service
node_auth_route -->|"verifies Google token"| node_oauth_service
node_oauth_service -.->|"verifies identity"| node_google
node_safety_route -->|"reads and writes"| node_database
node_ai_route -->|"reads and writes"| node_database
node_ai_service -.->|"requests completions"| node_openai
node_news_service -.->|"requests analysis"| node_openai

click node_main "https://github.com/lemon-2-ade/trove-backend/blob/main/main.py"
click node_auth_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/auth.py"
click node_users_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/users.py"
click node_preferences_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/preferences.py"
click node_cities_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/cities.py"
click node_exploration_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/exploration.py"
click node_itinerary_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/itinerary.py"
click node_quests_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/quests.py"
click node_badges_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/badges.py"
click node_leaderboards_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/leaderboards.py"
click node_ai_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/ai_recommendations.py"
click node_journal_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/journal.py"
click node_safety_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/safety.py"
click node_emergency_route "https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/emergency_contacts.py"
click node_news_service "https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/news_analysis_ai.py"
click node_scraping_service "https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/news_scraping_agent.py"
click node_auth_service "https://github.com/lemon-2-ade/trove-backend/blob/main/app/core/auth.py"
click node_oauth_service "https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/google_oauth.py"
click node_ai_service "https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/ai_agent.py"
click node_maps_service "https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/google_maps.py"
click node_database "https://github.com/lemon-2-ade/trove-backend/blob/main/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_main,node_auth_route,node_users_route,node_preferences_route toneBlue
class node_cities_route,node_exploration_route,node_itinerary_route,node_ai_route,node_journal_route toneAmber
class node_quests_route,node_badges_route,node_leaderboards_route toneMint
class node_safety_route,node_emergency_route,node_news_service,node_scraping_service toneRose
class node_auth_service,node_oauth_service,node_ai_service,node_maps_service,node_database,node_traveler,node_google,node_openai toneIndigo
```

## Components

### API entry and identity

- [FastAPI app](https://github.com/lemon-2-ade/trove-backend/blob/main/main.py): `main.py`
- [Authentication](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [User profiles](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/users.py): `app/api/routes/users.py`
- [Preferences](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/preferences.py): `app/api/routes/preferences.py`

### Travel and exploration

- [Cities](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/cities.py): `app/api/routes/cities.py`
- [Place exploration](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/exploration.py): `app/api/routes/exploration.py`
- [Itineraries](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/itinerary.py): `app/api/routes/itinerary.py`
- [AI recommendations](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/ai_recommendations.py): `app/api/routes/ai_recommendations.py`
- [Travel journal](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/journal.py): `app/api/routes/journal.py`

### Gamification and community

- [Quests](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/quests.py): `app/api/routes/quests.py`
- [Badges](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/badges.py): `app/api/routes/badges.py`
- [Leaderboards](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/leaderboards.py): `app/api/routes/leaderboards.py`

### Safety and assistance

- [Safety reports](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/safety.py): `app/api/routes/safety.py`
- [Emergency contacts](https://github.com/lemon-2-ade/trove-backend/blob/main/app/api/routes/emergency_contacts.py): `app/api/routes/emergency_contacts.py`
- [News analysis](https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/news_analysis_ai.py): `app/services/news_analysis_ai.py`
- [News collection](https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/news_scraping_agent.py): `app/services/news_scraping_agent.py`

### Core services

- [Token and passwords](https://github.com/lemon-2-ade/trove-backend/blob/main/app/core/auth.py): `app/core/auth.py`
- [Google OAuth](https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/google_oauth.py): `app/services/google_oauth.py`
- [Travel AI agent](https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/ai_agent.py): `app/services/ai_agent.py`
- [Maps integration](https://github.com/lemon-2-ade/trove-backend/blob/main/app/services/google_maps.py): `app/services/google_maps.py`
- [Prisma database](https://github.com/lemon-2-ade/trove-backend/blob/main/app/core/database.py): `app/core/database.py`

### Other components

- **Traveler**
- **Google identity**
- **OpenAI**

## Connections

- Traveler → FastAPI app: calls API
- FastAPI app → Authentication: routes requests
- FastAPI app → User profiles: routes requests
- FastAPI app → Preferences: routes requests
- FastAPI app → Cities: routes requests
- FastAPI app → Place exploration: routes requests
- FastAPI app → Itineraries: routes requests
- FastAPI app → Quests: routes requests
- FastAPI app → Badges: routes requests
- FastAPI app → Leaderboards: routes requests
- FastAPI app → AI recommendations: routes requests
- FastAPI app → Travel journal: routes requests
- FastAPI app → Safety reports: routes requests
- FastAPI app → Emergency contacts: routes requests
- FastAPI app → Prisma database: initializes
- Authentication → Prisma database: reads and writes
- Authentication → Token and passwords: creates tokens
- Authentication → Google OAuth: verifies Google token
- Google OAuth → Google identity: verifies identity
- Safety reports → Prisma database: reads and writes
- AI recommendations → Prisma database: reads and writes
- Travel AI agent → OpenAI: requests completions
- News analysis → OpenAI: requests analysis