# thamizh-arasu/contextiva-prototype-bmad architecture

> Architecture diagram of the GitHub repository thamizh-arasu/contextiva-prototype-bmad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thamizh-arasu/contextiva-prototype-bmad
- Repository: https://github.com/thamizh-arasu/contextiva-prototype-bmad

## Overview

Contextiva is organized as a layered, domain-driven Python service with a single FastAPI application at the edge, a use-case/application layer in the middle, domain models as the business core, and infrastructure adapters for persistence, cache, crawling, and LLM providers.

#### What the system is

The repository implements a knowledge engine for AI agents. Its main purpose is to ingest project documents and external content, store and version that knowledge, and expose it through:
- a REST API under `/api/v1`
- a planned/partial MCP integration surface for agent tooling
- RAG-oriented search and synthesis workflows

The system is not a general CMS; it is centered around knowledge organization for projects and retrieval for downstream AI consumers.

#### Main runtime boundary

The runtime entry point is the FastAPI app in `src/api/main.py`. Around that edge are:
- `src/api/v1/routes/*` for HTTP endpoints
- `src/api/middleware/logging_middleware.py` for request tracing / structured logging
- `src/api/dependencies.py` for dependency injection into routes
- `src/api/v1/schemas/*` for request/response validation and API contracts

This API layer is the external contract for clients, including human users, scripts, and AI agents.

#### Core layers and responsibilities

##### 1) API layer
This layer is purely transport and validation:
- routes for `auth`, `projects`, `documents`, `tasks`, `knowledge`, and `rag`
- Pydantic schemas for each resource
- middleware for logging and request correlation

The API layer translates HTTP requests into application use cases and returns typed responses. It should not contain domain rules.

##### 2) Application layer
This is the orchestration layer that coordinates workflows across domain objects and infrastructure.

It is split into:
- `src/application/use_cases/projects/create_project.py`
- `src/application/use_cases/knowledge/query_knowledge.py`
- `src/application/use_cases/ingest_knowledge.py`
- `src/application/use_cases/crawl_knowledge.py`

and reusable services in:
- `src/application/services/text_extractor.py`
- `src/application/services/text_chunker.py`
- `src/application/services/hybrid_search_service.py`
- `src/application/services/reranking_service.py`
- `src/application/services/synthesis_service.py`

This layer owns multi-step business flows such as:
- creating projects
- ingesting documents or crawled content
- breaking text into chunks
- searching and reranking knowledge
- synthesizing an answer for RAG queries

##### 3) Domain layer
The domain layer contains the core business entities:
- `project`
- `document`
- `task`
- `knowledge`
- `user`

These are the stable concepts around which the application is built. The README and schema/migration names indicate that:
- projects are the root organizing concept
- documents are versioned source artifacts
- tasks are project-scoped work items
- knowledge items are indexed/searchable derived records
- users support auth and ownership

This is the business boundary that should remain independent of FastAPI, the database, Redis, or any provider vendor.

##### 4) Infrastructure layer
Infrastructure provides concrete implementations for persistence and external systems:

###### Database repositories
Under `src/infrastructure/database/repositories/` there are repositories for:
- projects
- documents
- tasks
- knowledge
- users

These are the persistence adapters that isolate the rest of the code from PostgreSQL details.

###### Cache
`src/infrastructure/cache/redis_cache.py` is the Redis adapter. Cache is optional according to configuration, but it is part of the performance architecture for repeated retrievals and possibly RAG lookups.

###### External integrations
- `src/infrastructure/external/crawler/crawler_client.py` handles crawling external URLs or documentation sources
- `src/infrastructure/external/llm/provider_factory.py` selects among LLM backends
- provider implementations exist for:
  - OpenAI
  - Anthropic
  - Ollama
  - OpenRouter

This external boundary is important because RAG, synthesis, and ingestion depend on third-party AI services and web sources.

##### 5) Shared cross-cutting utilities
`src/shared/` contains reusable platform concerns:
- `shared/config/settings.py` for environment-driven configuration
- `shared/config/logging.py` for log setup
- `shared/infrastructure/database/connection.py` for the async database pool
- `shared/utils/security.py` for auth/security helpers
- `shared/utils/errors.py` for app-wide error handling
- `shared/utils/versioning.py` for semantic/version-related helpers

These are not business features; they are shared operational concerns used across layers.

#### Main data flows

##### Project management flow
Request path:
- API route in `projects`
- application use case, especially create project
- project repository
- PostgreSQL

Projects act as the anchor for other entities. Documents, tasks, and knowledge records are all organized in relation to a project, so the project boundary is central to the data model.

##### Document ingestion and versioning flow
Request path:
- API route in `documents` or knowledge upload/crawl entrypoints
- document-related application logic
- text extraction and chunking services
- document repository and knowledge repository
- PostgreSQL, with pgvector-enabled tables for retrieval-oriented storage

Documents are treated as source artifacts, while knowledge items are the retrievable derived records. That separation is important for diagramming the system: raw content and searchable knowledge are distinct storage concerns.

##### Knowledge crawl / upload flow
Request path:
- `/api/v1/knowledge/crawl` or `/api/v1/knowledge/upload`
- `crawl_knowledge` or `ingest_knowledge` use case
- crawler client or file/text extraction service
- chunking service
- persistence into document/knowledge tables
- later retrieval through search services

This flow bridges external content sources into the internal knowledge index.

##### RAG query flow
Request path:
- `/api/v1/rag/query`
- knowledge query use case
- hybrid search service
- optional reranking service
- synthesis service
- knowledge repository and database search
- optional Redis cache
- LLM provider for answer generation or synthesis

This is the most important end-user AI workflow. The architecture supports a layered retrieval pipeline rather than a single database lookup:
1. retrieve candidate knowledge
2. combine semantic and keyword signals
3. rerank if enabled
4. synthesize a final response if enabled

##### Authentication and security flow
There is an `auth` route and security utilities under `shared/utils/security.py`. The README describes JWT-based authentication and RBAC support/stubs. In architecture terms, auth is a cross-cutting boundary that protects the API layer and is enforced through dependencies rather than being embedded in business logic.

#### Persistence and schema boundary

The database is PostgreSQL with `pgvector` enabled by migration. Migrations show the schema evolution clearly:
- enable pgvector
- create `projects`
- create `users`
- create `documents`
- create `tasks`
- create `knowledge_items`
- add a full-text search index

This tells you the system’s storage model is hybrid:
- relational tables for core entities
- vector search for semantic retrieval
- full-text indexing for keyword-based retrieval

That hybrid storage design is the foundation for the RAG/search layer.

#### Infrastructure and deployment model

The repo is container-first:
- `Dockerfile` for the application image
- `docker-compose.yml` for the local multi-service stack
- PostgreSQL with pgvector as the primary datastore
- Redis as the cache layer

The application is configured entirely through environment variables, including:
- app host/port
- PostgreSQL connection details
- Redis connection details
- LLM provider selection and model settings
- embedding and RAG behavior flags
- CORS and observability options

This means deployment architecture is environment-driven and service-oriented, not embedded in code.

#### Observability and operational concerns

The system includes:
- structured logging
- request logging middleware
- health checking with database connectivity
- error-handling utilities
- configuration-driven behavior

These concerns sit outside the core business layer but are essential to runtime architecture. They support debugging, readiness checks, and production operations.

#### Testing topology

The test layout mirrors the architecture:
- unit tests for domain models, shared utilities, and application services
- integration tests for repositories, provider factory, and cache
- e2e tests for API endpoints

That test stratification reinforces the layer boundaries and indicates which parts are intended to be isolated versus integration-tested.

#### Inferred subsystem map

For an architecture diagram, the main boxes should be:

1. Clients
   - human API consumers
   - AI agents
   - future MCP/tooling clients

2. API edge
   - FastAPI app
   - versioned HTTP routes
   - validation schemas
   - middleware

3. Application orchestration
   - project use cases
   - knowledge ingestion/query use cases
   - RAG/search services
   - extraction/chunking/reranking/synthesis services

4. Domain core
   - project, document, task, knowledge, user models

5. Infrastructure adapters
   - PostgreSQL repositories
   - Redis cache
   - crawler client
   - LLM provider factory and vendor providers

6. Shared platform services
   - config
   - logging
   - security
   - database connection
   - errors/versioning

7. Operational systems
   - PostgreSQL + pgvector
   - Redis
   - external LLM APIs
   - external web sources for crawling

#### Key architectural takeaway

The repository is built around a clean separation between:
- knowledge/workflow orchestration
- domain entities
- persistence/search infrastructure
- external AI and crawling services

The most important domain boundary is between raw content management (`documents`, `crawl/upload`) and derived retrievable knowledge (`knowledge_items`, RAG query). The most important technical boundary is between the application layer and the vendor-backed infrastructure layer, especially for LLMs, vector search, and caching.

Main entry points: [`src/api/v1/routes/projects.py`](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/v1/routes/projects.py) (HTTP Routes), [`src/api/dependencies.py`](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/dependencies.py) (Dependencies), [`src/application/use_cases/ingest_knowledge.py`](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/use_cases/ingest_knowledge.py) (Ingest Knowledge), [`src/shared/infrastructure/database/connection.py`](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/shared/infrastructure/database/connection.py) (DB Connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Clients"
  human_clients(("Humans<br/>consumer"))
  agent_clients(("Agents<br/>consumer"))
end

subgraph "API Edge"
  api_main["FastAPI App<br/>entrypoint<br/>[main.py]"]
  api_routes["HTTP Routes<br/>transport<br/>[projects.py]"]
  api_schemas["API Schemas<br/>contracts<br/>[project.py]"]
  api_middleware["Logging Middleware<br/>cross-cutting"]
  api_deps["Dependencies<br/>composition<br/>[dependencies.py]"]
end

subgraph "Application"
  project_uc["Create Project<br/>use case<br/>[create_project.py]"]
  ingest_uc["Ingest Knowledge<br/>use case"]
  crawl_uc["Crawl Knowledge<br/>use case<br/>[crawl_knowledge.py]"]
  query_uc["Query Knowledge<br/>use case<br/>[query_knowledge.py]"]
  extractor["Text Extractor<br/>[text_extractor.py]"]
  chunker["Text Chunker<br/>[text_chunker.py]"]
  search_svc["Hybrid Search"]
  rerank_svc["Reranking"]
  synthesis_svc["Synthesis"]
end

subgraph "Domain Core"
  project_model(("Project<br/>entity<br/>[project.py]"))
  document_model(("Document<br/>entity<br/>[document.py]"))
  task_model(("Task<br/>entity<br/>[task.py]"))
  knowledge_model(("Knowledge<br/>entity<br/>[knowledge.py]"))
  user_model(("User<br/>entity<br/>[user.py]"))
end

subgraph "Infrastructure"
  project_repo[("Project Repo")]
  document_repo[("Document Repo")]
  task_repo[("Task Repo<br/>[task_repository.py]")]
  knowledge_repo[("Knowledge Repo")]
  user_repo[("User Repo<br/>[user_repository.py]")]
  redis_cache[("Redis Cache<br/>cache adapter<br/>[redis_cache.py]")]
  crawler_client["Crawler Client<br/>external adapter<br/>[crawler_client.py]"]
  llm_factory["LLM Factory<br/>provider selector"]
  llm_providers["LLM Providers<br/>vendor adapters<br/>[base.py]"]
end

subgraph "Shared Platform"
  settings["Settings<br/>config<br/>[settings.py]"]
  logging["Logging<br/>config<br/>[logging.py]"]
  db_connection[("DB Connection<br/>infrastructure<br/>[connection.py]")]
  security["Security Utils<br/>[security.py]"]
end

subgraph "Operational Systems"
end

human_clients -->|"REST requests"| api_main
agent_clients -->|"REST / MCP"| api_main
api_main -->|"mounts"| api_routes
api_main -->|"wraps"| api_middleware
api_routes -->|"validates"| api_schemas
api_routes -->|"injects"| api_deps
api_routes -->|"creates"| project_uc
api_routes -->|"ingests"| ingest_uc
api_routes -->|"crawls"| crawl_uc
api_routes -->|"queries"| query_uc
api_deps -->|"wires"| project_repo
api_deps -->|"wires"| document_repo
api_deps -->|"wires"| task_repo
api_deps -->|"wires"| knowledge_repo
api_deps -->|"wires"| user_repo
api_deps -->|"wires"| search_svc
api_deps -->|"reads"| settings
project_uc -->|"uses"| project_model
project_uc -->|"persists"| project_repo
ingest_uc -->|"extracts"| extractor
ingest_uc -->|"chunks"| chunker
ingest_uc -->|"stores"| document_repo
ingest_uc -->|"indexes"| knowledge_repo
crawl_uc -->|"fetches"| crawler_client
crawl_uc -->|"delegates"| ingest_uc
query_uc -->|"retrieves"| search_svc
query_uc -->|"reranks"| rerank_svc
query_uc -->|"synthesizes"| synthesis_svc
search_svc -->|"searches"| knowledge_repo
search_svc -->|"consults"| redis_cache
synthesis_svc -->|"selects"| llm_factory
llm_factory -->|"routes to"| llm_providers
knowledge_repo -->|"queries"| db_connection
project_repo -->|"queries"| db_connection
document_repo -->|"queries"| db_connection
task_repo -->|"queries"| db_connection
user_repo -->|"queries"| db_connection
api_routes -->|"protects"| security
settings -->|"configures"| db_connection
settings -->|"configures"| redis_cache
settings -->|"configures"| llm_factory

click api_main "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/api/main.py"
click api_routes "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/api/v1/routes/projects.py"
click api_schemas "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/api/v1/schemas/project.py"
click api_middleware "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/api/middleware/logging_middleware.py"
click api_deps "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/api/dependencies.py"
click project_uc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/use_cases/projects/create_project.py"
click ingest_uc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/use_cases/ingest_knowledge.py"
click crawl_uc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/use_cases/crawl_knowledge.py"
click query_uc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/use_cases/knowledge/query_knowledge.py"
click extractor "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/services/text_extractor.py"
click chunker "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/services/text_chunker.py"
click search_svc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/services/hybrid_search_service.py"
click rerank_svc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/services/reranking_service.py"
click synthesis_svc "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/application/services/synthesis_service.py"
click project_model "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/domain/models/project.py"
click document_model "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/domain/models/document.py"
click task_model "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/domain/models/task.py"
click knowledge_model "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/domain/models/knowledge.py"
click user_model "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/domain/models/user.py"
click project_repo "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/database/repositories/project_repository.py"
click document_repo "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/database/repositories/document_repository.py"
click task_repo "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/database/repositories/task_repository.py"
click knowledge_repo "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/database/repositories/knowledge_repository.py"
click user_repo "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/database/repositories/user_repository.py"
click redis_cache "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/cache/redis_cache.py"
click crawler_client "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/external/crawler/crawler_client.py"
click llm_factory "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/external/llm/provider_factory.py"
click llm_providers "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/infrastructure/external/llm/providers/base.py"
click settings "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/shared/config/settings.py"
click logging "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/shared/config/logging.py"
click db_connection "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/shared/infrastructure/database/connection.py"
click security "https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/main/src/shared/utils/security.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 human_clients,agent_clients toneBlue
class api_main,api_routes,api_schemas,api_middleware,api_deps toneAmber
class project_uc,ingest_uc,crawl_uc,query_uc,extractor,chunker,search_svc,rerank_svc,synthesis_svc toneMint
class project_model,document_model,task_model,knowledge_model,user_model toneRose
class project_repo,document_repo,task_repo,knowledge_repo,user_repo,redis_cache,crawler_client,llm_factory,llm_providers toneIndigo
class settings,logging,db_connection,security toneTeal
```

## Components

### Clients

API consumers and agent tooling

- **Humans**: consumer · Human users of the REST API
- **Agents**: consumer · AI agents and future MCP tooling

### API Edge

FastAPI entrypoint, routes, schemas, and middleware

- [FastAPI App](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/main.py): entrypoint · Application entrypoint and router assembly · `src/api/main.py`
- [HTTP Routes](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/v1/routes/projects.py): transport · Versioned REST endpoints for auth, projects, documents, tasks, knowledge, and rag · `src/api/v1/routes/projects.py`
- [API Schemas](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/v1/schemas/project.py): contracts · Pydantic request and response models · `src/api/v1/schemas/project.py`
- [Logging Middleware](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/middleware/logging_middleware.py): cross-cutting · Request logging and correlation · `src/api/middleware/logging_middleware.py`
- [Dependencies](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/api/dependencies.py): composition · Route dependency wiring for services and repositories · `src/api/dependencies.py`

### Application

Use cases and orchestration services

- [Create Project](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/use_cases/projects/create_project.py): use case · Coordinates project creation workflows · `src/application/use_cases/projects/create_project.py`
- [Ingest Knowledge](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/use_cases/ingest_knowledge.py): use case · Orchestrates upload and ingestion flows · `src/application/use_cases/ingest_knowledge.py`
- [Crawl Knowledge](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/use_cases/crawl_knowledge.py): use case · Orchestrates crawling and intake of external content · `src/application/use_cases/crawl_knowledge.py`
- [Query Knowledge](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/use_cases/knowledge/query_knowledge.py): use case · Coordinates retrieval and answer generation · `src/application/use_cases/knowledge/query_knowledge.py`
- [Text Extractor](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/services/text_extractor.py): service · Extracts text from source artifacts · `src/application/services/text_extractor.py`
- [Text Chunker](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/services/text_chunker.py): service · Splits content into retrieval-friendly chunks · `src/application/services/text_chunker.py`
- [Hybrid Search](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/services/hybrid_search_service.py): service · Combines keyword and semantic retrieval · `src/application/services/hybrid_search_service.py`
- [Reranking](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/services/reranking_service.py): service · Reorders candidate results by relevance · `src/application/services/reranking_service.py`
- [Synthesis](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/application/services/synthesis_service.py): service · Builds final RAG responses from retrieved context · `src/application/services/synthesis_service.py`

### Domain Core

Business entities and invariants

- [Project](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/domain/models/project.py): entity · Root organizing concept for knowledge work · `src/domain/models/project.py`
- [Document](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/domain/models/document.py): entity · Versioned source artifact · `src/domain/models/document.py`
- [Task](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/domain/models/task.py): entity · Project-scoped work item · `src/domain/models/task.py`
- [Knowledge](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/domain/models/knowledge.py): entity · Derived searchable knowledge record · `src/domain/models/knowledge.py`
- [User](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/domain/models/user.py): entity · Authenticated user and ownership subject · `src/domain/models/user.py`

### Infrastructure

Persistence and external adapters

- [Project Repo](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/database/repositories/project_repository.py): repository · Persistence adapter for projects · `src/infrastructure/database/repositories/project_repository.py`
- [Document Repo](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/database/repositories/document_repository.py): repository · Persistence adapter for documents · `src/infrastructure/database/repositories/document_repository.py`
- [Task Repo](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/database/repositories/task_repository.py): repository · Persistence adapter for tasks · `src/infrastructure/database/repositories/task_repository.py`
- [Knowledge Repo](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/database/repositories/knowledge_repository.py): repository · Persistence adapter for knowledge items and retrieval queries · `src/infrastructure/database/repositories/knowledge_repository.py`
- [User Repo](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/database/repositories/user_repository.py): repository · Persistence adapter for users · `src/infrastructure/database/repositories/user_repository.py`
- [Redis Cache](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/cache/redis_cache.py): cache adapter · Optional cache for retrieval and repeated lookups · `src/infrastructure/cache/redis_cache.py`
- [Crawler Client](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/external/crawler/crawler_client.py): external adapter · Fetches external web or documentation content · `src/infrastructure/external/crawler/crawler_client.py`
- [LLM Factory](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/external/llm/provider_factory.py): provider selector · Selects the active LLM backend · `src/infrastructure/external/llm/provider_factory.py`
- [LLM Providers](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/infrastructure/external/llm/providers/base.py): vendor adapters · OpenAI, Anthropic, Ollama, and OpenRouter integrations · `src/infrastructure/external/llm/providers/base.py`

### Shared Platform

Cross-cutting configuration and utilities

- [Settings](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/shared/config/settings.py): config · Environment-driven application configuration · `src/shared/config/settings.py`
- [Logging](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/shared/config/logging.py): config · Shared logging setup · `src/shared/config/logging.py`
- [DB Connection](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/shared/infrastructure/database/connection.py): infrastructure · Async database pool and connection management · `src/shared/infrastructure/database/connection.py`
- [Security Utils](https://github.com/thamizh-arasu/contextiva-prototype-bmad/blob/HEAD/src/shared/utils/security.py): utility · Auth and JWT helper functions · `src/shared/utils/security.py`

## Connections

- Humans → FastAPI App: REST requests · Humans call the HTTP API
- Agents → FastAPI App: REST / MCP · Agents interact through the API and planned tool surface
- FastAPI App → HTTP Routes: mounts · Registers versioned routes
- FastAPI App → Logging Middleware: wraps · Adds request logging and correlation
- HTTP Routes → API Schemas: validates · Uses typed request and response contracts
- HTTP Routes → Dependencies: injects · Resolves services and repositories per request
- HTTP Routes → Create Project: creates · Project endpoints invoke project use cases
- HTTP Routes → Ingest Knowledge: ingests · Document and knowledge upload flows
- HTTP Routes → Crawl Knowledge: crawls · Knowledge crawl entrypoints
- HTTP Routes → Query Knowledge: queries · RAG query endpoints
- Dependencies → Project Repo: wires · Provides persistence adapters
- Dependencies → Document Repo: wires · Provides persistence adapters
- Dependencies → Task Repo: wires · Provides persistence adapters
- Dependencies → Knowledge Repo: wires · Provides persistence adapters
- Dependencies → User Repo: wires · Provides persistence adapters
- Dependencies → Hybrid Search: wires · Provides retrieval service dependencies
- Dependencies → Settings: reads · Uses environment configuration
- Create Project → Project: uses · Operates on project entities
- Create Project → Project Repo: persists · Stores projects
- Ingest Knowledge → Text Extractor: extracts · Pulls text from source documents
- Ingest Knowledge → Text Chunker: chunks · Prepares content for indexing
- Ingest Knowledge → Document Repo: stores · Persists source artifacts
- Ingest Knowledge → Knowledge Repo: indexes · Creates retrievable knowledge records
- Crawl Knowledge → Crawler Client: fetches · Retrieves external content
- Crawl Knowledge → Ingest Knowledge: delegates · Hands crawled content to ingestion flow
- Query Knowledge → Hybrid Search: retrieves · Collects candidate knowledge
- Query Knowledge → Reranking: reranks · Optionally improves result ordering
- Query Knowledge → Synthesis: synthesizes · Generates final answer text
- Hybrid Search → Knowledge Repo: searches · Queries the knowledge index
- Hybrid Search → Redis Cache: consults · Uses cache when enabled
- Synthesis → LLM Factory: selects · Obtains the configured LLM backend
- LLM Factory → LLM Providers: routes to · Chooses one of the vendor adapters
- Knowledge Repo → DB Connection: queries · Uses the shared async database connection
- Project Repo → DB Connection: queries · Uses the shared async database connection
- Document Repo → DB Connection: queries · Uses the shared async database connection
- Task Repo → DB Connection: queries · Uses the shared async database connection
- User Repo → DB Connection: queries · Uses the shared async database connection
- HTTP Routes → Security Utils: protects · Auth dependencies and JWT helpers secure routes
- Settings → DB Connection: configures · Drives database connectivity
- Settings → Redis Cache: configures · Drives cache behavior
- Settings → LLM Factory: configures · Selects provider and model settings
