# realabidhasnine/codemonk architecture

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

- Interactive diagram: https://gitdiagram.com/realabidhasnine/codemonk
- Repository: https://github.com/realabidhasnine/codemonk

## Overview

CodeMonk is a repository-understanding platform intended to turn source code into structural knowledge and developer-facing architectural answers. Its documented workflow is repository ingestion, AST and dependency extraction, asynchronous indexing into graph and vector stores, hybrid context retrieval, AI reasoning, and delivery through developer interfaces. The tree shows service skeletons and shared components; many pipeline capabilities are described in the README but their implementations were not sampled. Those links reflect documented architecture, not verified runtime wiring.

Main entry points: [`services/search-service`](https://github.com/realabidhasnine/codemonk/tree/main/services/search-service) (Hybrid retrieval), [`services/api-gateway`](https://github.com/realabidhasnine/codemonk/tree/main/services/api-gateway) (API gateway), [`services/repository-service`](https://github.com/realabidhasnine/codemonk/tree/main/services/repository-service) (Repository service), [`services/code-analysis-service`](https://github.com/realabidhasnine/codemonk/tree/main/services/code-analysis-service) (AST parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Code ingestion"]
  node_repo_service["Repository service"]
  node_ast_parser["AST parsing"]
  node_extractor["Structure extractor"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_event_bus["Kafka event bus"]
  node_graph_store[("Knowledge graph")]
  node_vector_store[("Vector store")]
  node_retrieval["Hybrid retrieval"]
  node_graph_queries["Graph queries"]
  node_impact["Impact analysis"]
end

subgraph group_intelligence["AI and delivery"]
  node_ai_service["AI reasoning"]
  node_gateway["API gateway"]
end

subgraph group_platform["Platform services"]
  node_config["Configuration server"]
  node_discovery["Service discovery"]
  node_shared_errors["Shared API errors"]
  node_documentation[("Documentation records")]
  node_documentation_repo["Documentation repository"]
end

node_developer(("Developer"))
node_repository["Git repository"]
node_llm["Code LLM"]
node_dev_clients["CLI, IDE, web"]

node_developer -->|"selects code"| node_repository
node_repository -->|"ingests source"| node_repo_service
node_repo_service -->|"supplies files"| node_ast_parser
node_ast_parser -->|"parses structure"| node_extractor
node_extractor -->|"publishes events"| node_event_bus
node_event_bus -->|"indexes relations"| node_graph_store
node_event_bus -->|"indexes embeddings"| node_vector_store
node_graph_store -->|"provides relations"| node_retrieval
node_vector_store -->|"provides matches"| node_retrieval
node_retrieval -->|"assembles context"| node_ai_service
node_ai_service -->|"reasons with"| node_llm
node_llm -->|"returns insights"| node_gateway
node_gateway -->|"serves answers"| node_dev_clients
node_graph_store -.->|"queries graph"| node_graph_queries
node_graph_store -.->|"supports analysis"| node_impact
node_developer -->|"submits questions"| node_gateway
node_documentation_repo -->|"persists records"| node_documentation

click node_repo_service "https://github.com/realabidhasnine/codemonk/tree/main/services/repository-service"
click node_ast_parser "https://github.com/realabidhasnine/codemonk/tree/main/services/code-analysis-service"
click node_extractor "https://github.com/realabidhasnine/codemonk/tree/main/services/code-analysis-service"
click node_retrieval "https://github.com/realabidhasnine/codemonk/tree/main/services/search-service"
click node_graph_queries "https://github.com/realabidhasnine/codemonk/blob/main/libs/common-core/src/main/java/com/codemonk/common/service/GraphQueryService.java"
click node_impact "https://github.com/realabidhasnine/codemonk/tree/main/services/knowledge-service"
click node_ai_service "https://github.com/realabidhasnine/codemonk/tree/main/services/ai-service"
click node_gateway "https://github.com/realabidhasnine/codemonk/tree/main/services/api-gateway"
click node_config "https://github.com/realabidhasnine/codemonk/tree/main/services/config-server"
click node_discovery "https://github.com/realabidhasnine/codemonk/tree/main/services/discovery-server"
click node_shared_errors "https://github.com/realabidhasnine/codemonk/blob/main/libs/common-core/src/main/java/com/codemonk/common/exception/GlobalExceptionHandler.java"
click node_documentation "https://github.com/realabidhasnine/codemonk/blob/main/libs/common-core/src/main/java/com/codemonk/common/service/DocumentationEntity.java"
click node_documentation_repo "https://github.com/realabidhasnine/codemonk/blob/main/services/repository-service/src/main/java/com/codemonk/repository/service/DocumentationRepository.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_repo_service,node_ast_parser,node_extractor toneBlue
class node_event_bus,node_graph_store,node_vector_store,node_retrieval,node_graph_queries,node_impact toneAmber
class node_ai_service,node_gateway toneMint
class node_config,node_discovery,node_shared_errors,node_documentation,node_documentation_repo toneRose
class node_developer,node_repository,node_llm,node_dev_clients toneIndigo
```

## Components

### Code ingestion

- [Repository service](https://github.com/realabidhasnine/codemonk/tree/main/services/repository-service): `services/repository-service`
- [AST parsing](https://github.com/realabidhasnine/codemonk/tree/main/services/code-analysis-service): `services/code-analysis-service`
- [Structure extractor](https://github.com/realabidhasnine/codemonk/tree/main/services/code-analysis-service): `services/code-analysis-service`

### Knowledge and retrieval

- **Kafka event bus**
- **Knowledge graph**
- **Vector store**
- [Hybrid retrieval](https://github.com/realabidhasnine/codemonk/tree/main/services/search-service): `services/search-service`
- [Graph queries](https://github.com/realabidhasnine/codemonk/blob/main/libs/common-core/src/main/java/com/codemonk/common/service/GraphQueryService.java): `libs/common-core/src/main/java/com/codemonk/common/service/GraphQueryService.java`
- [Impact analysis](https://github.com/realabidhasnine/codemonk/tree/main/services/knowledge-service): `services/knowledge-service`

### AI and delivery

- [AI reasoning](https://github.com/realabidhasnine/codemonk/tree/main/services/ai-service): `services/ai-service`
- [API gateway](https://github.com/realabidhasnine/codemonk/tree/main/services/api-gateway): `services/api-gateway`

### Platform services

- [Configuration server](https://github.com/realabidhasnine/codemonk/tree/main/services/config-server): `services/config-server`
- [Service discovery](https://github.com/realabidhasnine/codemonk/tree/main/services/discovery-server): `services/discovery-server`
- [Shared API errors](https://github.com/realabidhasnine/codemonk/blob/main/libs/common-core/src/main/java/com/codemonk/common/exception/GlobalExceptionHandler.java): `libs/common-core/src/main/java/com/codemonk/common/exception/GlobalExceptionHandler.java`
- [Documentation records](https://github.com/realabidhasnine/codemonk/blob/main/libs/common-core/src/main/java/com/codemonk/common/service/DocumentationEntity.java): `libs/common-core/src/main/java/com/codemonk/common/service/DocumentationEntity.java`
- [Documentation repository](https://github.com/realabidhasnine/codemonk/blob/main/services/repository-service/src/main/java/com/codemonk/repository/service/DocumentationRepository.java): `services/repository-service/src/main/java/com/codemonk/repository/service/DocumentationRepository.java`

### Other components

- **Developer**
- **Git repository**
- **Code LLM**
- **CLI, IDE, web**

## Connections

- Developer → Git repository: selects code
- Git repository → Repository service: ingests source
- Repository service → AST parsing: supplies files
- AST parsing → Structure extractor: parses structure
- Structure extractor → Kafka event bus: publishes events
- Kafka event bus → Knowledge graph: indexes relations
- Kafka event bus → Vector store: indexes embeddings
- Knowledge graph → Hybrid retrieval: provides relations
- Vector store → Hybrid retrieval: provides matches
- Hybrid retrieval → AI reasoning: assembles context
- AI reasoning → Code LLM: reasons with
- Code LLM → API gateway: returns insights
- API gateway → CLI, IDE, web: serves answers
- Knowledge graph → Graph queries: queries graph
- Knowledge graph → Impact analysis: supports analysis
- Developer → API gateway: submits questions
- Documentation repository → Documentation records: persists records (evidence: `services/repository-service/src/main/java/com/codemonk/repository/service/DocumentationRepository.java`)
