# cesar0k/smart-recipe-finder-backend architecture

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

- Interactive diagram: https://gitdiagram.com/cesar0k/smart-recipe-finder-backend
- Repository: https://github.com/cesar0k/smart-recipe-finder-backend

## Overview

Smart Recipe Finder is a FastAPI backend for recipe discovery and social cooking. A user submits a search or recipe request to the API; recipe services apply semantic search, filters, and ranking, then return results. Other major workflows cover recipe drafts and moderation, accounts and profiles, engagement, and notifications. The README documents service-layer coordination with PostgreSQL, Redis, vector search, object storage, email, and WebSockets. Several subsystem links below are documented rather than verified in unsampled endpoint code.

Main entry points: [`app/services/recipe/recipe_service.py`](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/recipe_service.py) (Recipe and search), [`app/services/notification/notification_service.py`](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/notification/notification_service.py) (In-app notifications), [`app/api/v1/api.py`](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/api.py) (REST API), [`app/api/v1/endpoints/auth.py`](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/endpoints/auth.py) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api["REST API<br/>[api.py]"]
  node_auth_ep["Auth endpoints<br/>[auth.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_google_auth["Google OAuth"]
  node_users["User profiles<br/>[user_service.py]"]
end

subgraph group_recipes["Recipe discovery"]
  node_recipe_ep["Recipe endpoints<br/>[recipes.py]"]
  node_recipe_service["Recipe and search<br/>[recipe_service.py]"]
  node_tag_service["Tag classification<br/>[tag_service.py]"]
  node_vector["Semantic vector search<br/>[vector_store.py]"]
  node_recipe_models[("Recipe records<br/>[recipe.py]")]
  node_cache_keys["Search cache keys<br/>[cache_keys.py]"]
end

subgraph group_community["Community and moderation"]
  node_social["Follows and engagement<br/>[follow_service.py]"]
  node_comments["Comments<br/>[comment_service.py]"]
  node_moderation["Content moderation"]
end

subgraph group_delivery["Notifications and delivery"]
  node_notifications["In-app notifications"]
  node_email["Transactional email<br/>[email_service.py]"]
  node_websocket["WebSocket delivery<br/>[ws_manager.py]"]
end

subgraph group_platform["Runtime infrastructure"]
  node_cache[("Redis cache<br/>[cache.py]")]
  node_database[("PostgreSQL sessions<br/>[session.py]")]
  node_storage[("Image object storage<br/>[s3_client.py]")]
end

node_user(("Platform user"))
node_external_email["SMTP relay"]

node_user -->|"requests"| node_api
node_api -->|"routes to"| node_auth_ep
node_api -->|"routes to"| node_recipe_ep
node_auth_ep -->|"calls"| node_auth_service
node_auth_ep -->|"calls"| node_google_auth
node_auth_service -->|"uses"| node_users
node_recipe_ep -.->|"delegates to"| node_recipe_service
node_recipe_service -->|"reads and writes"| node_recipe_models
node_recipe_service -->|"searches"| node_vector
node_recipe_service -->|"invalidates"| node_cache_keys
node_cache_keys -->|"keys cache"| node_cache
node_recipe_service -->|"delegates to"| node_tag_service
node_recipe_service -->|"uploads images"| node_storage
node_recipe_service -->|"uses sessions"| node_database
node_recipe_service -->|"caches results"| node_cache
node_recipe_service -->|"semantic retrieval"| node_vector
node_social -->|"notifies"| node_notifications
node_comments -->|"notifies"| node_notifications
node_moderation -->|"alerts users"| node_notifications
node_notifications -->|"pushes updates"| node_websocket
node_notifications -->|"schedules email"| node_email
node_email -.->|"sends via SMTP"| node_external_email
node_notifications -->|"persists"| node_database

click node_api "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/api.py"
click node_auth_ep "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/endpoints/auth.py"
click node_auth_service "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/auth/auth_service.py"
click node_google_auth "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/auth/google_auth_service.py"
click node_users "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/social/user_service.py"
click node_recipe_ep "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/endpoints/recipes.py"
click node_recipe_service "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/recipe_service.py"
click node_tag_service "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/tag_service.py"
click node_vector "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/vector_store.py"
click node_recipe_models "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/models/recipe/recipe.py"
click node_cache_keys "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/cache_keys.py"
click node_cache "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/cache.py"
click node_social "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/social/follow_service.py"
click node_comments "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/comment/comment_service.py"
click node_moderation "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/moderation/moderation_service.py"
click node_notifications "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/notification/notification_service.py"
click node_email "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/notification/email_service.py"
click node_websocket "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/ws_manager.py"
click node_database "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/db/session.py"
click node_storage "https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/s3_client.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_api,node_auth_ep,node_auth_service,node_google_auth,node_users,node_user toneBlue
class node_recipe_ep,node_recipe_service,node_tag_service,node_vector,node_recipe_models,node_cache_keys toneAmber
class node_social,node_comments,node_moderation toneMint
class node_notifications,node_email,node_websocket toneRose
class node_cache,node_database,node_storage,node_external_email toneIndigo
```

## Components

### API and identity

- [REST API](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/api.py): `app/api/v1/api.py`
- [Auth endpoints](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/endpoints/auth.py): `app/api/v1/endpoints/auth.py`
- [Authentication](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/auth/auth_service.py): `app/services/auth/auth_service.py`
- [Google OAuth](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/auth/google_auth_service.py): `app/services/auth/google_auth_service.py`
- [User profiles](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/social/user_service.py): `app/services/social/user_service.py`

### Recipe discovery

- [Recipe endpoints](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/api/v1/endpoints/recipes.py): `app/api/v1/endpoints/recipes.py`
- [Recipe and search](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/recipe_service.py): `app/services/recipe/recipe_service.py`
- [Tag classification](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/tag_service.py): `app/services/recipe/tag_service.py`
- [Semantic vector search](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/vector_store.py): `app/core/vector_store.py`
- [Recipe records](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/models/recipe/recipe.py): `app/models/recipe/recipe.py`
- [Search cache keys](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/recipe/cache_keys.py): `app/services/recipe/cache_keys.py`

### Community and moderation

- [Follows and engagement](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/social/follow_service.py): `app/services/social/follow_service.py`
- [Comments](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/comment/comment_service.py): `app/services/comment/comment_service.py`
- [Content moderation](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/moderation/moderation_service.py): `app/services/moderation/moderation_service.py`

### Notifications and delivery

- [In-app notifications](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/notification/notification_service.py): `app/services/notification/notification_service.py`
- [Transactional email](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/services/notification/email_service.py): `app/services/notification/email_service.py`
- [WebSocket delivery](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/ws_manager.py): `app/core/ws_manager.py`

### Runtime infrastructure

- [Redis cache](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/cache.py): `app/core/cache.py`
- [PostgreSQL sessions](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/db/session.py): `app/db/session.py`
- [Image object storage](https://github.com/cesar0k/smart-recipe-finder-backend/blob/main/app/core/s3_client.py): `app/core/s3_client.py`

### Other components

- **Platform user**
- **SMTP relay**

## Connections

- Platform user → REST API: requests
- REST API → Auth endpoints: routes to (evidence: `app/api/v1/api.py`)
- REST API → Recipe endpoints: routes to (evidence: `app/api/v1/api.py`)
- Auth endpoints → Authentication: calls (evidence: `app/api/v1/endpoints/auth.py`)
- Auth endpoints → Google OAuth: calls (evidence: `app/api/v1/endpoints/auth.py`)
- Authentication → User profiles: uses (evidence: `app/services/auth/auth_service.py`)
- Recipe endpoints → Recipe and search: delegates to
- Recipe and search → Recipe records: reads and writes (evidence: `app/services/recipe/recipe_service.py`)
- Recipe and search → Semantic vector search: searches (evidence: `app/services/recipe/recipe_service.py`)
- Recipe and search → Search cache keys: invalidates (evidence: `app/services/recipe/recipe_service.py`)
- Search cache keys → Redis cache: keys cache (evidence: `app/services/recipe/cache_keys.py`)
- Recipe and search → Tag classification: delegates to (evidence: `app/services/recipe/tag_service.py`)
- Recipe and search → Image object storage: uploads images (evidence: `app/services/recipe/recipe_service.py`)
- Recipe and search → PostgreSQL sessions: uses sessions
- Recipe and search → Redis cache: caches results (evidence: `app/services/recipe/recipe_service.py`)
- Recipe and search → Semantic vector search: semantic retrieval (evidence: `app/services/recipe/recipe_service.py`)
- Follows and engagement → In-app notifications: notifies (evidence: `app/services/social/follow_service.py`)
- Comments → In-app notifications: notifies (evidence: `app/services/comment/comment_service.py`)
- Content moderation → In-app notifications: alerts users (evidence: `app/services/moderation/moderation_service.py`)
- In-app notifications → WebSocket delivery: pushes updates (evidence: `app/services/notification/notification_service.py`)
- In-app notifications → Transactional email: schedules email (evidence: `app/services/notification/notification_service.py`)
- Transactional email → SMTP relay: sends via SMTP
- In-app notifications → PostgreSQL sessions: persists (evidence: `app/services/notification/notification_service.py`)
