# alexey-obukhov/psy-supabase architecture

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

- Interactive diagram: https://gitdiagram.com/alexey-obukhov/psy-supabase
- Repository: https://github.com/alexey-obukhov/psy-supabase

## Overview

Psy-Supabase is a psychological-support chatbot backend that combines Supabase-backed knowledge and interaction history with retrieval, recurring-theme detection, and therapeutic response generation. Its user workflow enters through the chat API, initializes model and database services, processes the question with RAG and psychological analysis, then returns a generated response. The graph also preserves documented embedding/vector search, associative memory, emotion and topic analysis, prompt selection, and safety capabilities. Relationship evidence comes from the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not assumed.

Main entry points: [`psy_supabase/core/rag_processor.py`](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/rag_processor.py) (RAG processor), [`psy_supabase/main.py`](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/main.py) (Chat API), [`psy_supabase/core/database.py`](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/database.py) (Database manager), [`psy_supabase/core/pain_point_detector.py`](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/pain_point_detector.py) (Pain detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Chat entry"]
  node_api["Chat API<br/>[main.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_retrieval["Retrieval and memory"]
  node_rag["RAG processor<br/>[rag_processor.py]"]
  node_dynamic["Dynamic retrieval<br/>[dynamic_rag.py]"]
  node_context["Context selection"]
  node_memory["Associative memory"]
  node_database["Database manager<br/>[database.py]"]
  node_embeddings["Embedding utilities<br/>[embedding_utils.py]"]
  node_vectors["Vector utilities<br/>[vector_utils.py]"]
end

subgraph group_psychology["Psychological analysis"]
  node_pain["Pain detection"]
  node_emotion["Emotion analysis"]
  node_nlp["Text analysis<br/>[nlp_utils.py]"]
  node_mappings["Therapeutic mappings"]
end

subgraph group_generation["Response generation"]
  node_models["Model manager<br/>[model_manager.py]"]
  node_response["Response builder"]
  node_textgen["Text generator<br/>[text_generator.py]"]
  node_prompts["Prompt selection<br/>[prompt_selector.py]"]
  node_safety["Safety checks<br/>[safety_handler.py]"]
  node_templates["Therapy templates"]
end

node_user(("User"))
node_supabase[("Supabase store")]

node_user -->|"sends question"| node_api
node_api -->|"uses database"| node_database
node_api -->|"gets generator"| node_models
node_api -->|"creates processor"| node_rag
node_api -->|"tracks pain points"| node_pain
node_api -->|"reads settings"| node_config
node_database -.->|"reads and writes"| node_supabase
node_rag -->|"retrieves context"| node_database
node_rag -->|"requests retrieval"| node_dynamic
node_rag -->|"uses context"| node_context
node_rag -->|"uses memory"| node_memory
node_rag -->|"processes embeddings"| node_embeddings
node_rag -->|"uses models"| node_models
node_dynamic -->|"queries history"| node_database
node_pain -->|"checks patterns"| node_database
node_pain -->|"analyzes emotion"| node_emotion
node_pain -->|"analyzes text"| node_nlp
node_pain -->|"uses themes"| node_mappings
node_context -->|"queries vectors"| node_database
node_context -->|"uses vector tools"| node_vectors
node_models -->|"provides generator"| node_textgen
node_rag -->|"uses response builder"| node_response
node_response -->|"generates text"| node_textgen
node_response -->|"selects prompt"| node_prompts
node_textgen -->|"selects prompt"| node_prompts
node_textgen -->|"uses templates"| node_templates
node_textgen -.->|"checks safety"| node_safety
node_mappings -->|"standardizes themes"| node_emotion

click node_api "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/main.py"
click node_config "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/config.py"
click node_models "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/model_manager.py"
click node_rag "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/rag_processor.py"
click node_dynamic "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/dynamic_rag.py"
click node_context "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/rag/context_determination.py"
click node_memory "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/memory/associative_memory.py"
click node_database "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/database.py"
click node_embeddings "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/embedding_utils.py"
click node_vectors "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/vector_utils.py"
click node_pain "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/pain_point_detector.py"
click node_emotion "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/semantic_emotion_detector.py"
click node_nlp "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/nlp_utils.py"
click node_mappings "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/therapeutic_mappings.py"
click node_response "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/response_generator.py"
click node_textgen "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/text_generator.py"
click node_prompts "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/prompt_selector.py"
click node_safety "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/safety_handler.py"
click node_templates "https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/templates/therapeutic_prompt.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_config,node_user toneBlue
class node_rag,node_dynamic,node_context,node_memory,node_database,node_embeddings,node_vectors,node_supabase toneAmber
class node_pain,node_emotion,node_nlp,node_mappings toneMint
class node_models,node_response,node_textgen,node_prompts,node_safety,node_templates toneRose
```

## Components

### Chat entry

- [Chat API](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/main.py): `psy_supabase/main.py`
- [Runtime config](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/config.py): `psy_supabase/config.py`

### Retrieval and memory

- [RAG processor](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/rag_processor.py): `psy_supabase/core/rag_processor.py`
- [Dynamic retrieval](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/dynamic_rag.py): `psy_supabase/core/dynamic_rag.py`
- [Context selection](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/rag/context_determination.py): `psy_supabase/rag/context_determination.py`
- [Associative memory](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/memory/associative_memory.py): `psy_supabase/memory/associative_memory.py`
- [Database manager](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/database.py): `psy_supabase/core/database.py`
- [Embedding utilities](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/embedding_utils.py): `psy_supabase/utilities/embedding_utils.py`
- [Vector utilities](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/vector_utils.py): `psy_supabase/utilities/vector_utils.py`

### Psychological analysis

- [Pain detection](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/pain_point_detector.py): `psy_supabase/core/pain_point_detector.py`
- [Emotion analysis](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/semantic_emotion_detector.py): `psy_supabase/utilities/semantic_emotion_detector.py`
- [Text analysis](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/nlp_utils.py): `psy_supabase/utilities/nlp_utils.py`
- [Therapeutic mappings](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/therapeutic_mappings.py): `psy_supabase/utilities/therapeutic_mappings.py`

### Response generation

- [Model manager](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/model_manager.py): `psy_supabase/core/model_manager.py`
- [Response builder](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/response_generator.py): `psy_supabase/core/response_generator.py`
- [Text generator](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/core/text_generator.py): `psy_supabase/core/text_generator.py`
- [Prompt selection](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/prompt_selector.py): `psy_supabase/utilities/prompt_selector.py`
- [Safety checks](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/safety_handler.py): `psy_supabase/utilities/safety_handler.py`
- [Therapy templates](https://github.com/alexey-obukhov/psy-supabase/blob/psy-supabase-pkg/psy_supabase/utilities/templates/therapeutic_prompt.py): `psy_supabase/utilities/templates/therapeutic_prompt.py`

### Other components

- **User**
- **Supabase store**

## Connections

- User → Chat API: sends question (evidence: `psy_supabase/main.py`)
- Chat API → Database manager: uses database (evidence: `psy_supabase/main.py`)
- Chat API → Model manager: gets generator (evidence: `psy_supabase/main.py`)
- Chat API → RAG processor: creates processor (evidence: `psy_supabase/main.py`)
- Chat API → Pain detection: tracks pain points (evidence: `psy_supabase/main.py`)
- Chat API → Runtime config: reads settings (evidence: `psy_supabase/main.py`)
- Database manager → Supabase store: reads and writes
- RAG processor → Database manager: retrieves context (evidence: `psy_supabase/core/rag_processor.py`)
- RAG processor → Dynamic retrieval: requests retrieval (evidence: `psy_supabase/core/rag_processor.py`)
- RAG processor → Context selection: uses context (evidence: `psy_supabase/core/rag_processor.py`)
- RAG processor → Associative memory: uses memory (evidence: `psy_supabase/core/rag_processor.py`)
- RAG processor → Embedding utilities: processes embeddings (evidence: `psy_supabase/core/rag_processor.py`)
- RAG processor → Model manager: uses models (evidence: `psy_supabase/core/rag_processor.py`)
- Dynamic retrieval → Database manager: queries history (evidence: `psy_supabase/core/dynamic_rag.py`)
- Pain detection → Database manager: checks patterns (evidence: `psy_supabase/core/pain_point_detector.py`)
- Pain detection → Emotion analysis: analyzes emotion (evidence: `psy_supabase/core/pain_point_detector.py`)
- Pain detection → Text analysis: analyzes text (evidence: `psy_supabase/core/pain_point_detector.py`)
- Pain detection → Therapeutic mappings: uses themes (evidence: `psy_supabase/core/pain_point_detector.py`)
- Context selection → Database manager: queries vectors (evidence: `psy_supabase/rag/context_determination.py`)
- Context selection → Vector utilities: uses vector tools (evidence: `psy_supabase/rag/context_determination.py`)
- Model manager → Text generator: provides generator (evidence: `psy_supabase/core/model_manager.py`)
- RAG processor → Response builder: uses response builder (evidence: `psy_supabase/core/rag_processor.py`)
- Response builder → Text generator: generates text (evidence: `psy_supabase/core/response_generator.py`)
- Response builder → Prompt selection: selects prompt (evidence: `psy_supabase/core/response_generator.py`)
- Text generator → Prompt selection: selects prompt (evidence: `psy_supabase/core/text_generator.py`)
- Text generator → Therapy templates: uses templates (evidence: `psy_supabase/core/text_generator.py`)
- Text generator → Safety checks: checks safety
- Therapeutic mappings → Emotion analysis: standardizes themes (evidence: `psy_supabase/utilities/semantic_emotion_detector.py`)