# ismail007-sk/soulmate architecture

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

- Interactive diagram: https://gitdiagram.com/ismail007-sk/soulmate
- Repository: https://github.com/ismail007-sk/soulmate

## Overview

Soulmate is an AI companion app: users sign up, configure a profile through onboarding, and use chat and soulmate features; the backend also extracts and retrieves memories. The graph includes the Expo client surfaces and FastAPI domain stages, plus the backend’s auth, persistence, and memory-worker layers. Backend routes and several service calls are visible in the supplied excerpts or SOURCE INDEX. Client-to-server wiring and some internal AI-service calls are not shown, so those connections are omitted.

Main entry points: [`fastapi-backend/app/main.py`](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/main.py) (API application), [`fastapi-backend/app/config/database.py`](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/config/database.py) (Database sessions), [`fastapi-backend/app/workers/memory_worker.py`](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/workers/memory_worker.py) (Memory worker), [`fastapi-backend/app/repositories/user_repository.py`](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/repositories/user_repository.py) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Expo Client"]
  node_auth_screens["Login and signup<br/>[login.tsx]"]
  node_onboarding["Profile onboarding<br/>[conversation.tsx]"]
  node_chat_screen["Chat screen<br/>[chat.tsx]"]
  node_settings_screen["Settings screen<br/>[settings.tsx]"]
  node_frontend_auth_api["Auth API client<br/>[auth.api.ts]"]
end

subgraph group_api["API Routing"]
  node_api_main["API application<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth_router.py]"]
  node_user_routes["User routes<br/>[user_router.py]"]
  node_chat_routes["Chat routes<br/>[chat_router.py]"]
  node_soulmate_routes["Soulmate routes<br/>[soulmate_router.py]"]
end

subgraph group_identity["Identity and Profiles"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_user_service["User service<br/>[user_service.py]"]
  node_auth_guard["Token and role guard<br/>[auth_dependency.py]"]
  node_user_repository["User repository<br/>[user_repository.py]"]
  node_user_model[("User records<br/>[users_model.py]")]
  node_database_config[("Database sessions<br/>[database.py]")]
end

subgraph group_companion["Companion Features"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_soulmate_service["Soulmate service"]
  node_llm_service["Language model integration<br/>[llm_service.py]"]
end

subgraph group_memory["Memory Processing"]
  node_memory_service["Memory service<br/>[memory_service.py]"]
  node_memory_worker["Memory worker<br/>[memory_worker.py]"]
  node_embedding_service["Embedding service"]
  node_memory_retrieval["Memory retrieval"]
  node_memory_repository[("Memory repository")]
  node_redis_config[("Redis connection<br/>[redis.py]")]
end

node_user(("App user"))

node_user -->|"uses"| node_auth_screens
node_user -->|"configures profile"| node_onboarding
node_user -->|"chats"| node_chat_screen
node_api_main -->|"registers"| node_auth_routes
node_api_main -->|"registers"| node_user_routes
node_api_main -->|"registers"| node_chat_routes
node_api_main -->|"registers"| node_soulmate_routes
node_api_main -->|"starts"| node_memory_worker
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"calls"| node_user_service
node_user_routes -->|"calls"| node_user_service
node_user_routes -->|"requires identity"| node_auth_guard
node_chat_routes -->|"calls"| node_chat_service
node_soulmate_routes -->|"calls"| node_soulmate_service
node_auth_guard -->|"looks up user"| node_user_repository
node_auth_guard -->|"gets session"| node_database_config
node_auth_service -->|"accesses users"| node_user_repository
node_auth_service -.->|"uses session"| node_database_config
node_user_service -->|"accesses users"| node_user_repository
node_user_repository -->|"queries"| node_user_model
node_user_model -->|"uses base"| node_database_config
node_memory_worker -->|"processes memories"| node_memory_service
node_memory_worker -->|"reads pending keys"| node_redis_config
node_memory_worker -->|"opens session"| node_database_config
node_memory_retrieval -->|"generates vectors"| node_embedding_service
node_memory_retrieval -->|"retrieves memories"| node_memory_repository
node_memory_repository -.->|"queries database"| node_database_config

click node_auth_screens "https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/(auth)/login.tsx"
click node_onboarding "https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/(onboarding)/conversation.tsx"
click node_chat_screen "https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/chat.tsx"
click node_settings_screen "https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/settings.tsx"
click node_frontend_auth_api "https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/features/auth/auth.api.ts"
click node_api_main "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/main.py"
click node_auth_routes "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/auth_router.py"
click node_user_routes "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/user_router.py"
click node_chat_routes "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/chat_router.py"
click node_soulmate_routes "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/soulmate_router.py"
click node_auth_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/auth_service.py"
click node_user_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/user_service.py"
click node_auth_guard "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/dependencies/auth_dependency.py"
click node_user_repository "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/repositories/user_repository.py"
click node_user_model "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/models/users_model.py"
click node_chat_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/chat_service.py"
click node_soulmate_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/soulmate_service.py"
click node_llm_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/llm_service.py"
click node_memory_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/memory_service.py"
click node_memory_worker "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/workers/memory_worker.py"
click node_embedding_service "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/embedding_service.py"
click node_memory_retrieval "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/memory_retrieval_service.py"
click node_memory_repository "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/repositories/memory_retrieval_repository.py"
click node_database_config "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/config/database.py"
click node_redis_config "https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/config/redis.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_auth_screens,node_onboarding,node_chat_screen,node_settings_screen,node_frontend_auth_api,node_user toneBlue
class node_api_main,node_auth_routes,node_user_routes,node_chat_routes,node_soulmate_routes toneAmber
class node_auth_service,node_user_service,node_auth_guard,node_user_repository,node_user_model,node_database_config toneMint
class node_chat_service,node_soulmate_service,node_llm_service toneRose
class node_memory_service,node_memory_worker,node_embedding_service,node_memory_retrieval,node_memory_repository,node_redis_config toneIndigo
```

## Components

### Expo Client

- [Login and signup](https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/(auth)/login.tsx): `expo-frontend/src/app/(auth)/login.tsx`
- [Profile onboarding](https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/(onboarding)/conversation.tsx): `expo-frontend/src/app/(onboarding)/conversation.tsx`
- [Chat screen](https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/chat.tsx): `expo-frontend/src/app/chat.tsx`
- [Settings screen](https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/app/settings.tsx): `expo-frontend/src/app/settings.tsx`
- [Auth API client](https://github.com/ismail007-sk/soulmate/blob/main/expo-frontend/src/features/auth/auth.api.ts): `expo-frontend/src/features/auth/auth.api.ts`

### API Routing

- [API application](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/main.py): `fastapi-backend/app/main.py`
- [Auth routes](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/auth_router.py): `fastapi-backend/app/routers/auth_router.py`
- [User routes](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/user_router.py): `fastapi-backend/app/routers/user_router.py`
- [Chat routes](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/chat_router.py): `fastapi-backend/app/routers/chat_router.py`
- [Soulmate routes](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/routers/soulmate_router.py): `fastapi-backend/app/routers/soulmate_router.py`

### Identity and Profiles

- [Auth service](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/auth_service.py): `fastapi-backend/app/services/auth_service.py`
- [User service](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/user_service.py): `fastapi-backend/app/services/user_service.py`
- [Token and role guard](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/dependencies/auth_dependency.py): `fastapi-backend/app/dependencies/auth_dependency.py`
- [User repository](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/repositories/user_repository.py): `fastapi-backend/app/repositories/user_repository.py`
- [User records](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/models/users_model.py): `fastapi-backend/app/models/users_model.py`
- [Database sessions](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/config/database.py): `fastapi-backend/app/config/database.py`

### Companion Features

- [Chat service](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/chat_service.py): `fastapi-backend/app/services/chat_service.py`
- [Soulmate service](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/soulmate_service.py): `fastapi-backend/app/services/soulmate_service.py`
- [Language model integration](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/llm_service.py): `fastapi-backend/app/services/llm_service.py`

### Memory Processing

- [Memory service](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/memory_service.py): `fastapi-backend/app/services/memory_service.py`
- [Memory worker](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/workers/memory_worker.py): `fastapi-backend/app/workers/memory_worker.py`
- [Embedding service](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/embedding_service.py): `fastapi-backend/app/services/embedding_service.py`
- [Memory retrieval](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/services/memory_retrieval_service.py): `fastapi-backend/app/services/memory_retrieval_service.py`
- [Memory repository](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/repositories/memory_retrieval_repository.py): `fastapi-backend/app/repositories/memory_retrieval_repository.py`
- [Redis connection](https://github.com/ismail007-sk/soulmate/blob/main/fastapi-backend/app/config/redis.py): `fastapi-backend/app/config/redis.py`

### Other components

- **App user**

## Connections

- App user → Login and signup: uses
- App user → Profile onboarding: configures profile
- App user → Chat screen: chats
- API application → Auth routes: registers (evidence: `fastapi-backend/app/main.py`)
- API application → User routes: registers (evidence: `fastapi-backend/app/main.py`)
- API application → Chat routes: registers (evidence: `fastapi-backend/app/main.py`)
- API application → Soulmate routes: registers (evidence: `fastapi-backend/app/main.py`)
- API application → Memory worker: starts (evidence: `fastapi-backend/app/main.py`)
- Auth routes → Auth service: calls (evidence: `fastapi-backend/app/routers/auth_router.py`)
- Auth routes → User service: calls (evidence: `fastapi-backend/app/routers/auth_router.py`)
- User routes → User service: calls (evidence: `fastapi-backend/app/routers/user_router.py`)
- User routes → Token and role guard: requires identity (evidence: `fastapi-backend/app/routers/user_router.py`)
- Chat routes → Chat service: calls (evidence: `fastapi-backend/app/routers/chat_router.py`)
- Soulmate routes → Soulmate service: calls (evidence: `fastapi-backend/app/routers/soulmate_router.py`)
- Token and role guard → User repository: looks up user (evidence: `fastapi-backend/app/dependencies/auth_dependency.py`)
- Token and role guard → Database sessions: gets session
- Auth service → User repository: accesses users (evidence: `fastapi-backend/app/services/auth_service.py`)
- Auth service → Database sessions: uses session
- User service → User repository: accesses users (evidence: `fastapi-backend/app/services/user_service.py`)
- User repository → User records: queries (evidence: `fastapi-backend/app/repositories/user_repository.py`)
- User records → Database sessions: uses base (evidence: `fastapi-backend/app/models/users_model.py`)
- Memory worker → Memory service: processes memories (evidence: `fastapi-backend/app/workers/memory_worker.py`)
- Memory worker → Redis connection: reads pending keys (evidence: `fastapi-backend/app/workers/memory_worker.py`)
- Memory worker → Database sessions: opens session (evidence: `fastapi-backend/app/workers/memory_worker.py`)
- Memory retrieval → Embedding service: generates vectors (evidence: `fastapi-backend/app/services/memory_retrieval_service.py`)
- Memory retrieval → Memory repository: retrieves memories (evidence: `fastapi-backend/app/services/memory_retrieval_service.py`)
- Memory repository → Database sessions: queries database