# mpairtech/emventory-ai-backend architecture

> Architecture diagram of the GitHub repository mpairtech/emventory-ai-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mpairtech/emventory-ai-backend
- Repository: https://github.com/mpairtech/emventory-ai-backend

## Overview

1. This repository is a FastAPI-based AI backend centered on semantic search and RAG. The main runtime entrypoint is `app/main.py`, which wires the API, configuration, dependency injection, and startup DB initialization.

2. The HTTP boundary lives under `app/api/v1/`. `router.py` aggregates the versioned routers, while the feature routers split the API by concern: `search`, `content`, `voice_router`, `speech_router`, and `revoke_router`. Request/response contracts are defined in `app/api/v1/schemas.py`.

3. The core application layer is in `app/core/`. It holds cross-cutting concerns that sit below the API and above the domain modules: configuration loading, exceptions, dependency providers, Redis cache client/service, LLM adapters, and vector-store helpers.

4. Persistence is PostgreSQL with SQLAlchemy models in `app/db/` and `app/db/models/`. The vector-specific model is `app/db/models/vector.py`, and `app/core/vector/pgvector.py` indicates the semantic index is implemented with `pgvector` inside Postgres rather than a separate search engine.

5. Redis is a second infrastructure dependency, wrapped by `app/core/cache/redis_client.py` and `cache_service.py`. Architecturally, this is a side cache alongside Postgres, likely used to speed up repeated lookups or store transient AI/search state.

6. The main domain logic is organized under `app/modules/`. `search/` is the most important module and appears to own the AI search pipeline: `service.py` orchestrates the flow, `repository.py` handles data access, `embeddings.py` handles embedding generation, and `stt.py` suggests speech-to-text support is part of the search experience.

7. `app/modules/content/service.py` is a separate business module for content operations. In architecture terms, it likely represents the ingestion/update side of the system: content enters here, is persisted in Postgres, and can then be indexed for semantic retrieval.

8. Model generation and AI inference are abstracted behind provider-specific clients in `app/core/llm/`. There are separate integrations for Gemini and OpenAI, which means the backend can switch or compare LLM providers without changing the API layer. The README confirms these are used for embeddings and RAG generation.

9. Speech-related functionality is split out from search. `app/modules/speech/huggingface_service.py` suggests a dedicated speech AI component backed by Hugging Face models, while the voice/speech routers expose it through the API. This keeps audio processing isolated from the core search and content flows.

10. The data flow is: client request → API router → domain service → repository/vector/cache/LLM dependencies → Postgres/pgvector, Redis, and external AI providers → API response. The key architectural boundary is that routers stay thin, while the domain modules and core adapters own the AI and storage behavior.

11. Operationally, the repo is container-friendly: there is a `Dockerfile`, `docker-compose.yml`, environment templates, and YAML config defaults under `config/` for local and production settings. Startup DB initialization and migration utilities live in `scripts/`, which suggests the schema and vector index setup are part of the deployment workflow.

12. There are also supporting artifacts that matter for understanding the system shape: `streamlit_test_app.py` for a local UI/test client, `app/tests/` for basic verification, and several docs focused on architecture, RAG, and pgvector checks. These are auxiliary to the runtime but help confirm the repo is an AI search backend rather than a general-purpose web app.

Main entry points: [`app/modules/search/service.py`](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/service.py) (Search Service), [`app/api/v1/router.py`](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/router.py) (API Router), [`app/core/dependencies.py`](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/dependencies.py) (Dependencies), [`app/main.py`](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/main.py) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["API"]
  node_node_main(("Main<br/>FastAPI entrypoint<br/>[main.py]"))
  node_node_api_router["API Router<br/>v1 router<br/>[router.py]"]
  node_node_search_router["Search<br/>HTTP router<br/>[search.py]"]
  node_node_content_router["Content<br/>HTTP router<br/>[content.py]"]
  node_node_voice_router["Voice<br/>HTTP router<br/>[voice_router.py]"]
  node_node_speech_router["Speech<br/>HTTP router<br/>[speech_router.py]"]
  node_node_revoke_router["Revoke<br/>HTTP router<br/>[revoke_router.py]"]
  node_node_schemas["Schemas<br/>API contracts<br/>[schemas.py]"]
end

subgraph group_group_core["Core"]
  node_node_config["Config<br/>settings<br/>[config.py]"]
  node_node_dependencies["Dependencies<br/>DI providers<br/>[dependencies.py]"]
  node_node_exceptions["Errors<br/>exception layer<br/>[exceptions.py]"]
  node_node_redis_client[("Redis Client<br/>cache client<br/>[redis_client.py]")]
  node_node_cache_service["Cache Service<br/>[cache_service.py]"]
  node_node_llm_gemini["Gemini<br/>LLM adapter<br/>[gemini.py]"]
  node_node_llm_openai["OpenAI<br/>LLM adapter<br/>[openai.py]"]
  node_node_pgvector["pgvector<br/>vector helper<br/>[pgvector.py]"]
end

subgraph group_group_modules["Modules"]
  node_node_search_service["Search Service<br/>search orchestration<br/>[service.py]"]
  node_node_search_repo["Search Repo<br/>data access<br/>[repository.py]"]
  node_node_embeddings["Embeddings<br/>embedding pipeline<br/>[embeddings.py]"]
  node_node_stt["STT<br/>speech-to-text<br/>[stt.py]"]
  node_node_content_service["Content Service<br/>content workflow<br/>[service.py]"]
  node_node_speech_service["HuggingFace Speech<br/>speech AI service"]
end

subgraph group_group_data["Data"]
  node_node_db_session[("DB Session<br/>SQLAlchemy session<br/>[session.py]")]
  node_node_vector_model["Vector Model<br/>ORM model<br/>[vector.py]"]
end

subgraph group_group_ops["Ops"]
  node_node_init_db["Init DB<br/>startup script<br/>[init_db.py]"]
  node_node_streamlit(("Test UI<br/>local client"))
end

node_node_main -->|"mounts API"| node_node_api_router
node_node_main -->|"loads"| node_node_config
node_node_main -->|"wires DI"| node_node_dependencies
node_node_main -->|"initializes"| node_node_init_db
node_node_api_router -->|"includes"| node_node_search_router
node_node_api_router -->|"includes"| node_node_content_router
node_node_api_router -->|"includes"| node_node_voice_router
node_node_api_router -->|"includes"| node_node_speech_router
node_node_api_router -->|"includes"| node_node_revoke_router
node_node_search_router -->|"uses"| node_node_schemas
node_node_content_router -->|"uses"| node_node_schemas
node_node_voice_router -->|"uses"| node_node_schemas
node_node_speech_router -->|"uses"| node_node_schemas
node_node_search_router -->|"calls"| node_node_search_service
node_node_content_router -->|"calls"| node_node_content_service
node_node_voice_router -->|"calls"| node_node_speech_service
node_node_speech_router -->|"calls"| node_node_speech_service
node_node_search_service -->|"queries"| node_node_search_repo
node_node_search_service -->|"generates"| node_node_embeddings
node_node_search_service -->|"transcribes"| node_node_stt
node_node_search_service -->|"caches"| node_node_cache_service
node_node_search_service -->|"generates"| node_node_llm_gemini
node_node_search_service -->|"generates"| node_node_llm_openai
node_node_search_repo -->|"persists"| node_node_db_session
node_node_search_repo -->|"stores"| node_node_vector_model
node_node_search_repo -->|"indexes"| node_node_pgvector
node_node_content_service -->|"persists"| node_node_db_session
node_node_content_service -->|"updates"| node_node_vector_model
node_node_cache_service -->|"uses"| node_node_redis_client
node_node_dependencies -->|"provides"| node_node_cache_service
node_node_dependencies -->|"provides"| node_node_db_session
node_node_dependencies -->|"provides"| node_node_llm_gemini
node_node_dependencies -->|"provides"| node_node_llm_openai
node_node_dependencies -->|"injects"| node_node_search_service
node_node_exceptions -.->|"guards"| node_node_search_router
node_node_exceptions -.->|"guards"| node_node_content_router
node_node_exceptions -.->|"guards"| node_node_voice_router
node_node_streamlit -.->|"calls"| node_node_api_router
node_node_init_db -->|"prepares"| node_node_db_session
node_node_init_db -->|"enables"| node_node_pgvector

click node_node_main "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/main.py"
click node_node_api_router "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/router.py"
click node_node_search_router "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/search.py"
click node_node_content_router "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/content.py"
click node_node_voice_router "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/voice_router.py"
click node_node_speech_router "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/speech_router.py"
click node_node_revoke_router "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/revoke_router.py"
click node_node_schemas "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/schemas.py"
click node_node_config "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/config.py"
click node_node_dependencies "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/dependencies.py"
click node_node_exceptions "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/exceptions.py"
click node_node_redis_client "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/cache/redis_client.py"
click node_node_cache_service "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/cache/cache_service.py"
click node_node_llm_gemini "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/llm/gemini.py"
click node_node_llm_openai "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/llm/openai.py"
click node_node_pgvector "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/vector/pgvector.py"
click node_node_db_session "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/db/session.py"
click node_node_vector_model "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/db/models/vector.py"
click node_node_search_service "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/service.py"
click node_node_search_repo "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/repository.py"
click node_node_embeddings "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/embeddings.py"
click node_node_stt "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/stt.py"
click node_node_content_service "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/content/service.py"
click node_node_speech_service "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/speech/huggingface_service.py"
click node_node_init_db "https://github.com/mpairtech/emventory-ai-backend/blob/main/scripts/init_db.py"
click node_node_streamlit "https://github.com/mpairtech/emventory-ai-backend/blob/main/app/streamlit_test_app.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_node_main,node_node_api_router,node_node_search_router,node_node_content_router,node_node_voice_router,node_node_speech_router,node_node_revoke_router,node_node_schemas toneBlue
class node_node_config,node_node_dependencies,node_node_exceptions,node_node_redis_client,node_node_cache_service,node_node_llm_gemini,node_node_llm_openai,node_node_pgvector toneAmber
class node_node_search_service,node_node_search_repo,node_node_embeddings,node_node_stt,node_node_content_service,node_node_speech_service toneMint
class node_node_db_session,node_node_vector_model toneRose
class node_node_init_db,node_node_streamlit toneIndigo
```

## Components

### API

HTTP boundary and request contracts

- [Main](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/main.py): FastAPI entrypoint · Application startup and wiring · `app/main.py`
- [API Router](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/router.py): v1 router · Aggregates versioned HTTP routes · `app/api/v1/router.py`
- [Search](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/search.py): HTTP router · Semantic search and RAG endpoints · `app/api/v1/routers/search.py`
- [Content](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/content.py): HTTP router · Content ingestion and management endpoints · `app/api/v1/routers/content.py`
- [Voice](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/voice_router.py): HTTP router · Voice interaction endpoints · `app/api/v1/routers/voice_router.py`
- [Speech](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/speech_router.py): HTTP router · Speech processing endpoints · `app/api/v1/speech_router.py`
- [Revoke](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/routers/revoke_router.py): HTTP router · Revocation and cancellation endpoints · `app/api/v1/routers/revoke_router.py`
- [Schemas](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/api/v1/schemas.py): API contracts · Request and response models · `app/api/v1/schemas.py`

### Core

Cross-cutting configuration, adapters, and infrastructure helpers

- [Config](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/config.py): settings · Environment and app configuration · `app/core/config.py`
- [Dependencies](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/dependencies.py): DI providers · FastAPI dependency wiring · `app/core/dependencies.py`
- [Errors](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/exceptions.py): exception layer · Shared API and domain exceptions · `app/core/exceptions.py`
- [Redis Client](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/cache/redis_client.py): cache client · Redis connection wrapper · `app/core/cache/redis_client.py`
- [Cache Service](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/cache/cache_service.py): cache service · Redis-backed caching operations · `app/core/cache/cache_service.py`
- [Gemini](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/llm/gemini.py): LLM adapter · Google Gemini integration · `app/core/llm/gemini.py`
- [OpenAI](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/llm/openai.py): LLM adapter · OpenAI integration · `app/core/llm/openai.py`
- [pgvector](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/core/vector/pgvector.py): vector helper · Postgres vector search helpers · `app/core/vector/pgvector.py`

### Modules

Domain services for search, content, and speech

- [Search Service](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/service.py): search orchestration · Coordinates query, retrieval, and generation · `app/modules/search/service.py`
- [Search Repo](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/repository.py): data access · Search persistence and retrieval access · `app/modules/search/repository.py`
- [Embeddings](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/embeddings.py): embedding pipeline · Embedding generation for semantic index · `app/modules/search/embeddings.py`
- [STT](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/search/stt.py): speech-to-text · Speech transcription support within search · `app/modules/search/stt.py`
- [Content Service](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/content/service.py): content workflow · Content ingestion and update logic · `app/modules/content/service.py`
- [HuggingFace Speech](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/modules/speech/huggingface_service.py): speech AI service · Dedicated speech model integration · `app/modules/speech/huggingface_service.py`

### Data

Persistence models and database session

- [DB Session](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/db/session.py): SQLAlchemy session · Database session management · `app/db/session.py`
- [Vector Model](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/db/models/vector.py): ORM model · Vector-enabled persistence model · `app/db/models/vector.py`

### Ops

Startup, initialization, and local tooling

- [Init DB](https://github.com/mpairtech/emventory-ai-backend/blob/main/scripts/init_db.py): startup script · Database bootstrap and migrations · `scripts/init_db.py`
- [Test UI](https://github.com/mpairtech/emventory-ai-backend/blob/main/app/streamlit_test_app.py): local client · Interactive local test application · `app/streamlit_test_app.py`

## Connections

- Main → API Router: mounts API · Main application mounts the versioned router
- Main → Config: loads · Startup reads runtime configuration
- Main → Dependencies: wires DI · Main app initializes dependency providers
- Main → Init DB: initializes · Startup database setup path
- API Router → Search: includes · Version router aggregates search endpoints
- API Router → Content: includes · Version router aggregates content endpoints
- API Router → Voice: includes · Version router aggregates voice endpoints
- API Router → Speech: includes · Version router aggregates speech endpoints
- API Router → Revoke: includes · Version router aggregates revoke endpoints
- Search → Schemas: uses · Search API depends on request/response contracts
- Content → Schemas: uses · Content API depends on request/response contracts
- Voice → Schemas: uses · Voice API depends on request/response contracts
- Speech → Schemas: uses · Speech API depends on request/response contracts
- Search → Search Service: calls · Search requests are handled by the domain service
- Content → Content Service: calls · Content requests are handled by the content service
- Voice → HuggingFace Speech: calls · Voice endpoints delegate to speech AI service
- Speech → HuggingFace Speech: calls · Speech endpoints delegate to speech AI service
- Search Service → Search Repo: queries · Search orchestration reads/writes through repository
- Search Service → Embeddings: generates · Search flow needs embeddings for semantic retrieval
- Search Service → STT: transcribes · Search flow can accept speech input
- Search Service → Cache Service: caches · Repeated or transient search state can be cached
- Search Service → Gemini: generates · LLM-backed RAG generation can use Gemini
- Search Service → OpenAI: generates · LLM-backed RAG generation can use OpenAI
- Search Repo → DB Session: persists · Repository uses SQLAlchemy sessions
- Search Repo → Vector Model: stores · Repository works with vector-enabled records
- Search Repo → pgvector: indexes · Semantic retrieval uses pgvector helpers
- Content Service → DB Session: persists · Content workflow writes through the database session
- Content Service → Vector Model: updates · Content changes can affect indexed vector records
- Cache Service → Redis Client: uses · Cache service is backed by Redis client
- Dependencies → Cache Service: provides · Dependency layer exposes cache service
- Dependencies → DB Session: provides · Dependency layer exposes database sessions
- Dependencies → Gemini: provides · Dependency layer can select Gemini adapter
- Dependencies → OpenAI: provides · Dependency layer can select OpenAI adapter
- Dependencies → Search Service: injects · Services are injected into HTTP handlers
- Errors → Search: guards · Shared error handling applies to routes
- Errors → Content: guards · Shared error handling applies to routes
- Errors → Voice: guards · Shared error handling applies to routes
- Test UI → API Router: calls · Local test client exercises the HTTP API
- Init DB → DB Session: prepares · Initialization scripts prepare the database layer
- Init DB → pgvector: enables · Bootstrap sets up vector support in Postgres