# deepsparkchaker/signalmira architecture

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

- Interactive diagram: https://gitdiagram.com/deepsparkchaker/signalmira
- Repository: https://github.com/deepsparkchaker/signalmira

## Overview

SignalMira is a tenant-scoped feedback review analytics product. Its main workflow imports review records, schedules durable enrichment stages, stores extracted signals and search indexes, then supports review browsing and retrieval. Separate product branches manage aspect groups and taxonomy proposals, and provide topic and retrieval exploration. The graph follows relationships visible in the excerpts, SOURCE INDEX references, or README; unsampled internals are represented only where the tree and documentation support them.

Main entry points: [`ingestion/review_worker.py`](https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/review_worker.py) (Stage worker), [`storage/postgres.py`](https://github.com/deepsparkchaker/signalmira/blob/main/storage/postgres.py) (PostgreSQL access), [`frontend/service.py`](https://github.com/deepsparkchaker/signalmira/blob/main/frontend/service.py) (Read service), [`indexing/rag_job.py`](https://github.com/deepsparkchaker/signalmira/blob/main/indexing/rag_job.py) (RAG indexing job)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Review ingestion"]
  node_ingest_api["Review ingest<br/>[review_ingest.py]"]
  node_review_schema["Review records<br/>[schemas.py]"]
  node_worker["Stage worker<br/>[review_worker.py]"]
end

subgraph group_enrich["Enrichment and taxonomy"]
  node_opinion_extract["Opinion extraction"]
  node_ner["Entity extraction<br/>[ner.py]"]
  node_sentiment["Sentiment analysis<br/>[sentiment.py]"]
  node_topics["Topic modeling<br/>[topics.py]"]
  node_language["Language analysis<br/>[language.py]"]
  node_taxonomy_pipeline["Taxonomy proposals"]
  node_taxonomy_store["Taxonomy store<br/>[taxonomy_store.py]"]
  node_aspect_groups["Aspect groups<br/>[aspect_groups.py]"]
  node_aspect_manager["Aspect manager<br/>[aspect_manager.py]"]
end

subgraph group_search["Index and retrieval"]
  node_chunking["Review chunking<br/>[chunking.py]"]
  node_rag_job["RAG indexing job<br/>[rag_job.py]"]
  node_chunk_store["Chunk store<br/>[chunk_store.py]"]
  node_embedders["Embedding models<br/>[embedders.py]"]
  node_semantic_search["Semantic search<br/>[semantic.py]"]
  node_hybrid_search["Hybrid search<br/>[hybrid.py]"]
  node_reranked_search["Reranked search<br/>[reranked_search.py]"]
end

subgraph group_app["User application"]
  node_app["Streamlit app<br/>[app.py]"]
  node_service["Read service<br/>[service.py]"]
  node_browser["Review browser<br/>[v1_browser.py]"]
  node_preview["Review preview<br/>[preview.py]"]
  node_aspect_page["Aspect Manager page<br/>[2_Aspect_Groups.py]"]
end

subgraph group_platform["Tenant and storage"]
  node_tenant_context["Tenant transactions<br/>[tenant_context.py]"]
  node_postgres["PostgreSQL access<br/>[postgres.py]"]
  node_database[("PostgreSQL database")]
end

node_user(("Analyst"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_service
node_ingest_api -->|"normalizes"| node_review_schema
node_ingest_api -->|"schedules stages"| node_worker
node_worker -->|"dispatches language"| node_language
node_worker -->|"dispatches NER"| node_ner
node_worker -->|"dispatches sentiment"| node_sentiment
node_worker -->|"dispatches opinions"| node_opinion_extract
node_worker -->|"dispatches topics"| node_topics
node_worker -->|"dispatches RAG"| node_rag_job
node_opinion_extract -.-> node_taxonomy_pipeline
node_taxonomy_pipeline -->|"reads labels"| node_taxonomy_store
node_aspect_manager -->|"uses taxonomy"| node_taxonomy_store
node_aspect_page -->|"manages taxonomy"| node_aspect_manager
node_aspect_page -->|"manages groups"| node_aspect_groups
node_aspect_page -->|"reads taxonomy"| node_taxonomy_store
node_rag_job -->|"creates chunks"| node_chunking
node_rag_job -->|"stores chunks"| node_chunk_store
node_rag_job -->|"encodes chunks"| node_embedders
node_semantic_search -->|"embeds queries"| node_embedders
node_hybrid_search -->|"embeds queries"| node_embedders
node_reranked_search -->|"searches candidates"| node_hybrid_search
node_reranked_search -->|"uses embeddings"| node_embedders
node_app -.->|"serves browsing"| node_browser
node_browser -->|"reads reviews"| node_service
node_preview -->|"uses service"| node_service
node_preview -.-> node_worker
node_service -->|"matches topics"| node_topics
node_ingest_api -->|"scopes writes"| node_tenant_context
node_worker -->|"scopes stages"| node_tenant_context
node_tenant_context -->|"sets tenant scope"| node_database
node_postgres -->|"connects to"| node_database
node_chunk_store -->|"uses storage"| node_postgres
node_hybrid_search -->|"queries store"| node_postgres
node_semantic_search -->|"queries store"| node_postgres
node_reranked_search -->|"queries store"| node_postgres
node_aspect_manager -->|"scopes writes"| node_tenant_context
node_service -->|"reads data"| node_postgres

click node_ingest_api "https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/review_ingest.py"
click node_review_schema "https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/schemas.py"
click node_worker "https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/review_worker.py"
click node_opinion_extract "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/langchain_opinions.py"
click node_ner "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/ner.py"
click node_sentiment "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/sentiment.py"
click node_topics "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/topics.py"
click node_language "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/language.py"
click node_taxonomy_pipeline "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/taxonomy_pipeline.py"
click node_taxonomy_store "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/taxonomy_store.py"
click node_aspect_groups "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/aspect_groups.py"
click node_aspect_manager "https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/aspect_manager.py"
click node_chunking "https://github.com/deepsparkchaker/signalmira/blob/main/indexing/chunking.py"
click node_rag_job "https://github.com/deepsparkchaker/signalmira/blob/main/indexing/rag_job.py"
click node_chunk_store "https://github.com/deepsparkchaker/signalmira/blob/main/indexing/chunk_store.py"
click node_embedders "https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/embedders.py"
click node_semantic_search "https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/semantic.py"
click node_hybrid_search "https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/hybrid.py"
click node_reranked_search "https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/reranked_search.py"
click node_app "https://github.com/deepsparkchaker/signalmira/blob/main/frontend/app.py"
click node_service "https://github.com/deepsparkchaker/signalmira/blob/main/frontend/service.py"
click node_browser "https://github.com/deepsparkchaker/signalmira/blob/main/frontend/v1_browser.py"
click node_preview "https://github.com/deepsparkchaker/signalmira/blob/main/frontend/ui/preview.py"
click node_aspect_page "https://github.com/deepsparkchaker/signalmira/blob/main/frontend/pages/2_Aspect_Groups.py"
click node_tenant_context "https://github.com/deepsparkchaker/signalmira/blob/main/security/tenant_context.py"
click node_postgres "https://github.com/deepsparkchaker/signalmira/blob/main/storage/postgres.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_ingest_api,node_review_schema,node_worker toneBlue
class node_opinion_extract,node_ner,node_sentiment,node_topics,node_language,node_taxonomy_pipeline,node_taxonomy_store,node_aspect_groups,node_aspect_manager toneAmber
class node_chunking,node_rag_job,node_chunk_store,node_embedders,node_semantic_search,node_hybrid_search,node_reranked_search toneMint
class node_app,node_service,node_browser,node_preview,node_aspect_page toneRose
class node_tenant_context,node_postgres,node_database,node_user toneIndigo
```

## Components

### Review ingestion

- [Review ingest](https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/review_ingest.py): `ingestion/review_ingest.py`
- [Review records](https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/schemas.py): `ingestion/schemas.py`
- [Stage worker](https://github.com/deepsparkchaker/signalmira/blob/main/ingestion/review_worker.py): `ingestion/review_worker.py`

### Enrichment and taxonomy

- [Opinion extraction](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/langchain_opinions.py): `enrichment/langchain_opinions.py`
- [Entity extraction](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/ner.py): `enrichment/ner.py`
- [Sentiment analysis](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/sentiment.py): `enrichment/sentiment.py`
- [Topic modeling](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/topics.py): `enrichment/topics.py`
- [Language analysis](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/language.py): `enrichment/language.py`
- [Taxonomy proposals](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/taxonomy_pipeline.py): `enrichment/taxonomy_pipeline.py`
- [Taxonomy store](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/taxonomy_store.py): `enrichment/taxonomy_store.py`
- [Aspect groups](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/aspect_groups.py): `enrichment/aspect_groups.py`
- [Aspect manager](https://github.com/deepsparkchaker/signalmira/blob/main/enrichment/aspect_manager.py): `enrichment/aspect_manager.py`

### Index and retrieval

- [Review chunking](https://github.com/deepsparkchaker/signalmira/blob/main/indexing/chunking.py): `indexing/chunking.py`
- [RAG indexing job](https://github.com/deepsparkchaker/signalmira/blob/main/indexing/rag_job.py): `indexing/rag_job.py`
- [Chunk store](https://github.com/deepsparkchaker/signalmira/blob/main/indexing/chunk_store.py): `indexing/chunk_store.py`
- [Embedding models](https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/embedders.py): `retrieval/embedders.py`
- [Semantic search](https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/semantic.py): `retrieval/semantic.py`
- [Hybrid search](https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/hybrid.py): `retrieval/hybrid.py`
- [Reranked search](https://github.com/deepsparkchaker/signalmira/blob/main/retrieval/reranked_search.py): `retrieval/reranked_search.py`

### User application

- [Streamlit app](https://github.com/deepsparkchaker/signalmira/blob/main/frontend/app.py): `frontend/app.py`
- [Read service](https://github.com/deepsparkchaker/signalmira/blob/main/frontend/service.py): `frontend/service.py`
- [Review browser](https://github.com/deepsparkchaker/signalmira/blob/main/frontend/v1_browser.py): `frontend/v1_browser.py`
- [Review preview](https://github.com/deepsparkchaker/signalmira/blob/main/frontend/ui/preview.py): `frontend/ui/preview.py`
- [Aspect Manager page](https://github.com/deepsparkchaker/signalmira/blob/main/frontend/pages/2_Aspect_Groups.py): `frontend/pages/2_Aspect_Groups.py`

### Tenant and storage

- [Tenant transactions](https://github.com/deepsparkchaker/signalmira/blob/main/security/tenant_context.py): `security/tenant_context.py`
- [PostgreSQL access](https://github.com/deepsparkchaker/signalmira/blob/main/storage/postgres.py): `storage/postgres.py`
- **PostgreSQL database**

### Other components

- **Analyst**

## Connections

- Analyst → Streamlit app: uses
- Streamlit app → Read service: routes to (evidence: `frontend/app.py`)
- Review ingest → Review records: normalizes (evidence: `ingestion/review_ingest.py`)
- Review ingest → Stage worker: schedules stages (evidence: `ingestion/review_ingest.py`)
- Stage worker → Language analysis: dispatches language (evidence: `ingestion/review_worker.py`)
- Stage worker → Entity extraction: dispatches NER (evidence: `ingestion/review_worker.py`)
- Stage worker → Sentiment analysis: dispatches sentiment (evidence: `ingestion/review_worker.py`)
- Stage worker → Opinion extraction: dispatches opinions (evidence: `ingestion/review_worker.py`)
- Stage worker → Topic modeling: dispatches topics (evidence: `ingestion/review_worker.py`)
- Stage worker → RAG indexing job: dispatches RAG (evidence: `ingestion/review_worker.py`)
- Opinion extraction → Taxonomy proposals
- Taxonomy proposals → Taxonomy store: reads labels (evidence: `enrichment/taxonomy_pipeline.py`)
- Aspect manager → Taxonomy store: uses taxonomy (evidence: `enrichment/aspect_manager.py`)
- Aspect Manager page → Aspect manager: manages taxonomy (evidence: `frontend/pages/2_Aspect_Groups.py`)
- Aspect Manager page → Aspect groups: manages groups (evidence: `frontend/pages/2_Aspect_Groups.py`)
- Aspect Manager page → Taxonomy store: reads taxonomy (evidence: `frontend/pages/2_Aspect_Groups.py`)
- RAG indexing job → Review chunking: creates chunks (evidence: `indexing/rag_job.py`)
- RAG indexing job → Chunk store: stores chunks (evidence: `indexing/rag_job.py`)
- RAG indexing job → Embedding models: encodes chunks (evidence: `indexing/rag_job.py`)
- Semantic search → Embedding models: embeds queries (evidence: `retrieval/semantic.py`)
- Hybrid search → Embedding models: embeds queries (evidence: `retrieval/hybrid.py`)
- Reranked search → Hybrid search: searches candidates (evidence: `retrieval/reranked_search.py`)
- Reranked search → Embedding models: uses embeddings (evidence: `retrieval/reranked_search.py`)
- Streamlit app → Review browser: serves browsing
- Review browser → Read service: reads reviews (evidence: `frontend/v1_browser.py`)
- Review preview → Read service: uses service (evidence: `frontend/ui/preview.py`)
- Review preview → Stage worker
- Read service → Topic modeling: matches topics (evidence: `frontend/service.py`)
- Review ingest → Tenant transactions: scopes writes (evidence: `ingestion/review_ingest.py`)
- Stage worker → Tenant transactions: scopes stages (evidence: `ingestion/review_worker.py`)
- Tenant transactions → PostgreSQL database: sets tenant scope (evidence: `security/tenant_context.py`)
- PostgreSQL access → PostgreSQL database: connects to (evidence: `storage/postgres.py`)
- Chunk store → PostgreSQL access: uses storage (evidence: `indexing/chunk_store.py`)
- Hybrid search → PostgreSQL access: queries store (evidence: `retrieval/hybrid.py`)
- Semantic search → PostgreSQL access: queries store (evidence: `retrieval/semantic.py`)
- Reranked search → PostgreSQL access: queries store (evidence: `retrieval/reranked_search.py`)
- Aspect manager → Tenant transactions: scopes writes (evidence: `enrichment/aspect_manager.py`)
- Read service → PostgreSQL access: reads data (evidence: `frontend/service.py`)
