mpairtech/emventory-ai-backend

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.