# kamranzafar/docman-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kamranzafar/docman-ai
- Repository: https://github.com/kamranzafar/docman-ai

## Overview

Docman AI is a document-management and RAG application. Its main flow accepts a document through the REST API, records metadata and stores file content, then starts a durable Temporal ingestion workflow that extracts, embeds, and indexes content. After indexing, summary and classification run asynchronously; search provides metadata, vector, and hybrid retrieval. The map also includes revision storage, Kafka-based index-metadata synchronization, and MCP agent access. Several internal implementations were not sampled, so README-documented relationships are cited rather than presented as inspected call paths.

Main entry points: [`docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java`](https://github.com/kamranzafar/docman-ai/blob/master/docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java) (REST controller), [`docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java`](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java) (Document service), [`docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java`](https://github.com/kamranzafar/docman-ai/blob/master/docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java) (MCP tools), [`docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentWorkflowImpl.java`](https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentWorkflowImpl.java) (Ingestion workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and agent access"]
  node_rest["REST controller"]
  node_mcp["MCP tools"]
end

subgraph group_lifecycle["Document lifecycle"]
  node_manager["Workflow manager"]
  node_docservice["Document service"]
  node_metadata["Document metadata<br/>[Document.java]"]
end

subgraph group_ingestion["Ingestion and AI"]
  node_workflow["Ingestion workflow"]
  node_activities["Workflow activities"]
  node_index["Index service"]
  node_summary["AI summarization"]
  node_classification["AI classification"]
end

subgraph group_retrieval["Search and retrieval"]
  node_search["Search service"]
end

subgraph group_stores["Storage and events"]
  node_revisions[("Revision history")]
  node_objects[("Object storage")]
  node_vectors[("Vector store")]
  node_mongo[("Metadata repository")]
  node_kafka["Kafka event bus"]
  node_sync["Index sync consumer"]
end

node_client(("API client"))
node_agent(("AI agent"))
node_temporal{{"Temporal service"}}
node_minio[("MinIO")]
node_opensearch[("OpenSearch")]

node_client -->|"calls API"| node_rest
node_rest -->|"manages metadata"| node_docservice
node_rest -->|"uploads content"| node_objects
node_rest -->|"starts workflow"| node_manager
node_rest -->|"dispatches searches"| node_search
node_agent -->|"uses tools"| node_mcp
node_mcp -->|"queries retrieval"| node_search
node_mcp -->|"looks up documents"| node_docservice
node_mcp -->|"gets download links"| node_objects
node_docservice -->|"persists metadata"| node_mongo
node_docservice -->|"records revisions"| node_revisions
node_manager -->|"starts execution"| node_temporal
node_temporal -->|"runs workflow"| node_workflow
node_workflow -->|"runs activities"| node_activities
node_activities -->|"reads file"| node_objects
node_activities -->|"indexes content"| node_index
node_index -->|"writes chunks"| node_vectors
node_vectors -->|"stores vectors"| node_opensearch
node_workflow -->|"runs after indexing"| node_summary
node_workflow -->|"runs after indexing"| node_classification
node_summary -->|"publishes result"| node_kafka
node_classification -->|"publishes result"| node_kafka
node_docservice -->|"publishes metadata changes"| node_kafka
node_kafka -->|"delivers updates"| node_sync
node_sync -->|"patches chunk metadata"| node_vectors
node_search -->|"runs vector retrieval"| node_vectors
node_search -->|"runs lexical retrieval"| node_opensearch

click node_rest "https://github.com/kamranzafar/docman-ai/blob/master/docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java"
click node_mcp "https://github.com/kamranzafar/docman-ai/blob/master/docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java"
click node_manager "https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/DocumentWorkflowManager.java"
click node_docservice "https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java"
click node_metadata "https://github.com/kamranzafar/docman-ai/blob/master/docman-domain/src/main/java/org/kamranzafar/docman/model/Document.java"
click node_revisions "https://github.com/kamranzafar/docman-ai/blob/master/docman-persistence/src/main/java/org/kamranzafar/docman/repository/DocumentRevisionRepository.java"
click node_workflow "https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentWorkflowImpl.java"
click node_activities "https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentActivitiesImpl.java"
click node_objects "https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/ObjectStoreServiceImpl.java"
click node_index "https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentIndexServiceImpl.java"
click node_vectors "https://github.com/kamranzafar/docman-ai/blob/master/docman-vector-opensearch/src/main/java/org/kamranzafar/docman/vectorstore/opensearch/OpenSearchDocumentVectorStore.java"
click node_summary "https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSummaryServiceImpl.java"
click node_classification "https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentClassificationServiceImpl.java"
click node_search "https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSearchServiceImpl.java"
click node_mongo "https://github.com/kamranzafar/docman-ai/blob/master/docman-persistence/src/main/java/org/kamranzafar/docman/repository/DocumentMetadataRepository.java"
click node_sync "https://github.com/kamranzafar/docman-ai/blob/master/docman-api/src/main/java/org/kamranzafar/docman/service/DocumentIndexSyncConsumer.java"

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_rest,node_mcp,node_client toneBlue
class node_manager,node_docservice,node_metadata,node_minio,node_opensearch toneAmber
class node_workflow,node_activities,node_index,node_summary,node_classification toneMint
class node_search toneRose
class node_revisions,node_objects,node_vectors,node_mongo,node_kafka,node_sync,node_agent,node_temporal toneIndigo
```

## Components

### API and agent access

- [REST controller](https://github.com/kamranzafar/docman-ai/blob/master/docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java): `docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java`
- [MCP tools](https://github.com/kamranzafar/docman-ai/blob/master/docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java): `docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java`

### Document lifecycle

- [Workflow manager](https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/DocumentWorkflowManager.java): `docman-workflow/src/main/java/org/kamranzafar/docman/wf/DocumentWorkflowManager.java`
- [Document service](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java): `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java`
- [Document metadata](https://github.com/kamranzafar/docman-ai/blob/master/docman-domain/src/main/java/org/kamranzafar/docman/model/Document.java): `docman-domain/src/main/java/org/kamranzafar/docman/model/Document.java`

### Ingestion and AI

- [Ingestion workflow](https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentWorkflowImpl.java): `docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentWorkflowImpl.java`
- [Workflow activities](https://github.com/kamranzafar/docman-ai/blob/master/docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentActivitiesImpl.java): `docman-workflow/src/main/java/org/kamranzafar/docman/wf/impl/DocumentActivitiesImpl.java`
- [Index service](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentIndexServiceImpl.java): `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentIndexServiceImpl.java`
- [AI summarization](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSummaryServiceImpl.java): `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSummaryServiceImpl.java`
- [AI classification](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentClassificationServiceImpl.java): `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentClassificationServiceImpl.java`

### Search and retrieval

- [Search service](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSearchServiceImpl.java): `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSearchServiceImpl.java`

### Storage and events

- [Revision history](https://github.com/kamranzafar/docman-ai/blob/master/docman-persistence/src/main/java/org/kamranzafar/docman/repository/DocumentRevisionRepository.java): `docman-persistence/src/main/java/org/kamranzafar/docman/repository/DocumentRevisionRepository.java`
- [Object storage](https://github.com/kamranzafar/docman-ai/blob/master/docman-service/src/main/java/org/kamranzafar/docman/service/impl/ObjectStoreServiceImpl.java): `docman-service/src/main/java/org/kamranzafar/docman/service/impl/ObjectStoreServiceImpl.java`
- [Vector store](https://github.com/kamranzafar/docman-ai/blob/master/docman-vector-opensearch/src/main/java/org/kamranzafar/docman/vectorstore/opensearch/OpenSearchDocumentVectorStore.java): `docman-vector-opensearch/src/main/java/org/kamranzafar/docman/vectorstore/opensearch/OpenSearchDocumentVectorStore.java`
- [Metadata repository](https://github.com/kamranzafar/docman-ai/blob/master/docman-persistence/src/main/java/org/kamranzafar/docman/repository/DocumentMetadataRepository.java): `docman-persistence/src/main/java/org/kamranzafar/docman/repository/DocumentMetadataRepository.java`
- **Kafka event bus**
- [Index sync consumer](https://github.com/kamranzafar/docman-ai/blob/master/docman-api/src/main/java/org/kamranzafar/docman/service/DocumentIndexSyncConsumer.java): `docman-api/src/main/java/org/kamranzafar/docman/service/DocumentIndexSyncConsumer.java`

### Other components

- **API client**
- **AI agent**
- **Temporal service**
- **MinIO**
- **OpenSearch**

## Connections

- API client → REST controller: calls API (evidence: `README.md`)
- REST controller → Document service: manages metadata (evidence: `docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java`)
- REST controller → Object storage: uploads content (evidence: `docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java`)
- REST controller → Workflow manager: starts workflow (evidence: `docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java`)
- REST controller → Search service: dispatches searches (evidence: `docman-api/src/main/java/org/kamranzafar/docman/api/DocumentController.java`)
- AI agent → MCP tools: uses tools (evidence: `README.md`)
- MCP tools → Search service: queries retrieval (evidence: `docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java`)
- MCP tools → Document service: looks up documents (evidence: `docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java`)
- MCP tools → Object storage: gets download links (evidence: `docman-mcp-server/src/main/java/org/kamranzafar/docman/mcp/DocumentMcpTools.java`)
- Document service → Metadata repository: persists metadata (evidence: `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java`)
- Document service → Revision history: records revisions (evidence: `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentServiceImpl.java`)
- Workflow manager → Temporal service: starts execution (evidence: `docman-workflow/src/main/java/org/kamranzafar/docman/wf/DocumentWorkflowManager.java`)
- Temporal service → Ingestion workflow: runs workflow (evidence: `README.md`)
- Ingestion workflow → Workflow activities: runs activities (evidence: `README.md`)
- Workflow activities → Object storage: reads file (evidence: `README.md`)
- Workflow activities → Index service: indexes content (evidence: `README.md`)
- Index service → Vector store: writes chunks (evidence: `README.md`)
- Vector store → OpenSearch: stores vectors (evidence: `docman-vector-opensearch/src/main/java/org/kamranzafar/docman/vectorstore/opensearch/OpenSearchDocumentVectorStore.java`)
- Ingestion workflow → AI summarization: runs after indexing (evidence: `README.md`)
- Ingestion workflow → AI classification: runs after indexing (evidence: `README.md`)
- AI summarization → Kafka event bus: publishes result (evidence: `README.md`)
- AI classification → Kafka event bus: publishes result (evidence: `README.md`)
- Document service → Kafka event bus: publishes metadata changes (evidence: `README.md`)
- Kafka event bus → Index sync consumer: delivers updates (evidence: `README.md`)
- Index sync consumer → Vector store: patches chunk metadata (evidence: `README.md`)
- Search service → Vector store: runs vector retrieval (evidence: `docman-service/src/main/java/org/kamranzafar/docman/service/impl/DocumentSearchServiceImpl.java`)
- Search service → OpenSearch: runs lexical retrieval (evidence: `README.md`)
