# datnguyentrung/ai-receptionist-be-py architecture

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

- Interactive diagram: https://gitdiagram.com/datnguyentrung/ai-receptionist-be-py
- Repository: https://github.com/datnguyentrung/ai-receptionist-be-py

## Overview

This repository contains two distinct products: a FastAPI face-embedding service and a separate ADK-based Taekwondo ingestion/GraphRAG application. The primary API workflow validates an uploaded image, detects exactly one face, and returns a validated vector; it does not persist or search embeddings. The ADK workflow stages document batches, accepts scoped semantic submissions, and only promotes graph data through an explicit fill step. README documents the broader ingestion, ontology, and retrieval capabilities; some corresponding implementation paths are unsampled, so their internal links are omitted where source evidence is unavailable.

Main entry points: [`app/agent/tools/ingestion_tools.py`](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/tools/ingestion_tools.py) (Ingestion tools), [`app/core/ingestion_runtime.py`](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/core/ingestion_runtime.py) (Runtime container), [`app/main.py`](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/main.py) (FastAPI application), [`app/services/face_embedding_service.py`](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/face_embedding_service.py) (Image processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_face["Face embedding API"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_face_api["Embedding endpoint"]
  node_face_service["Image processing"]
  node_insightface["Face model"]
  node_embedding_response["Embedding response"]
  node_error_handler["API error mapping"]
end

subgraph group_runtime["ADK ingestion"]
  node_adk_web["ADK Web process<br/>[adk_web.py]"]
  node_agent["ADK agent<br/>[agent.py]"]
  node_ingestion_skill["Ingestion skill<br/>[ingestion.py]"]
  node_ingestion_tools["Ingestion tools<br/>[ingestion_tools.py]"]
  node_ingestion_runtime["Runtime container"]
  node_document_processing["Document preparation"]
  node_staged_workspace["Batch workspace"]
  node_operations["Ingestion operations<br/>[operations.py]"]
  node_repository[("Workspace repository<br/>[repository.py]")]
  node_graph_store[("Neo4j graph store<br/>[graph_store.py]")]
end

subgraph group_rag["GraphRAG"]
  node_embeddings["Embedding provider<br/>[embeddings.py]"]
  node_graph_qa["Graph QA skill<br/>[tools.py]"]
  node_graphrag_tools["GraphRAG tools<br/>[graphrag_tools.py]"]
  node_retrieval["Knowledge retrieval<br/>[retrieval.py]"]
  node_answer["Cited answer"]
end

subgraph group_ontology["Ontology services"]
  node_ontology["Ontology management<br/>[ontology.py]"]
  node_ontology_lifecycle["Ontology lifecycle"]
  node_ontology_compiler["Ontology compiler"]
end

node_uploader(("Image uploader"))
node_adk_user(("Ingestion user"))

node_uploader -->|"uploads image"| node_fastapi
node_fastapi -->|"routes request"| node_face_api
node_face_api -->|"invokes processing"| node_face_service
node_face_service -->|"detects face"| node_insightface
node_face_service -->|"returns vector"| node_embedding_response
node_fastapi -->|"registers handlers"| node_error_handler
node_adk_user -->|"uses ingestion UI"| node_adk_web
node_adk_web -.->|"initializes runtime"| node_ingestion_runtime
node_agent -.->|"loads skill"| node_ingestion_skill
node_ingestion_skill -->|"invokes workflow tools"| node_ingestion_tools
node_ingestion_tools -->|"gets services"| node_ingestion_runtime
node_ingestion_tools -->|"composes operations"| node_operations
node_ingestion_tools -.->|"manages batches"| node_staged_workspace
node_ingestion_tools -.->|"persists workspace"| node_repository
node_ingestion_tools -->|"uses ontology primitives"| node_ontology
node_ingestion_tools -->|"fills graph"| node_graph_store
node_ingestion_runtime -->|"constructs repository"| node_repository
node_ingestion_runtime -->|"constructs graph store"| node_graph_store
node_ingestion_runtime -->|"constructs provider"| node_embeddings
node_ingestion_runtime -->|"constructs compiler"| node_ontology_compiler
node_ingestion_runtime -->|"constructs lifecycle"| node_ontology_lifecycle
node_ingestion_tools -.->|"prepares documents"| node_document_processing
node_graph_qa -.->|"calls retrieval tool"| node_graphrag_tools
node_graphrag_tools -->|"invokes retrieval"| node_retrieval
node_retrieval -->|"searches graph"| node_graph_store
node_retrieval -->|"uses embeddings"| node_embeddings
node_graph_qa -->|"returns cited answer"| node_answer
node_ontology -.->|"supports version lifecycle"| node_ontology_lifecycle
node_ontology_lifecycle -.->|"compiles ontology"| node_ontology_compiler

click node_fastapi "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/main.py"
click node_face_api "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/api/face_embedding_api.py"
click node_face_service "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/face_embedding_service.py"
click node_insightface "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/utils/insightface_utils.py"
click node_embedding_response "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/schemas/face_embedding_schema.py"
click node_error_handler "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/exceptions/exception_handler.py"
click node_adk_web "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/adk_web.py"
click node_agent "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/agent.py"
click node_ingestion_skill "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/skills/ingestion/ingestion.py"
click node_ingestion_tools "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/tools/ingestion_tools.py"
click node_ingestion_runtime "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/core/ingestion_runtime.py"
click node_document_processing "https://github.com/datnguyentrung/ai-receptionist-be-py/tree/main/app/services/ingestion/document"
click node_staged_workspace "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/workspace/staged_ingestion.py"
click node_operations "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/operations.py"
click node_repository "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/repository.py"
click node_ontology "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/ontology.py"
click node_ontology_lifecycle "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ontology_lifecycle.py"
click node_ontology_compiler "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ontology_compiler.py"
click node_graph_store "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/graph_store.py"
click node_embeddings "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/graphrag/embeddings.py"
click node_graph_qa "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/skills/graph-qa/tools.py"
click node_graphrag_tools "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/tools/graphrag_tools.py"
click node_retrieval "https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/graphrag/retrieval.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_fastapi,node_face_api,node_face_service,node_insightface,node_embedding_response,node_error_handler,node_adk_user toneBlue
class node_adk_web,node_agent,node_ingestion_skill,node_ingestion_tools,node_ingestion_runtime,node_document_processing,node_staged_workspace,node_operations,node_repository,node_graph_store toneAmber
class node_embeddings,node_graph_qa,node_graphrag_tools,node_retrieval,node_answer toneMint
class node_ontology,node_ontology_lifecycle,node_ontology_compiler toneRose
class node_uploader toneIndigo
```

## Components

### Face embedding API

- [FastAPI application](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/main.py): `app/main.py`
- [Embedding endpoint](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/api/face_embedding_api.py): `app/api/face_embedding_api.py`
- [Image processing](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/face_embedding_service.py): `app/services/face_embedding_service.py`
- [Face model](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/utils/insightface_utils.py): `app/utils/insightface_utils.py`
- [Embedding response](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/schemas/face_embedding_schema.py): `app/schemas/face_embedding_schema.py`
- [API error mapping](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/exceptions/exception_handler.py): `app/exceptions/exception_handler.py`

### ADK ingestion

- [ADK Web process](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/adk_web.py): `app/adk_web.py`
- [ADK agent](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Ingestion skill](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/skills/ingestion/ingestion.py): `app/agent/skills/ingestion/ingestion.py`
- [Ingestion tools](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/tools/ingestion_tools.py): `app/agent/tools/ingestion_tools.py`
- [Runtime container](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/core/ingestion_runtime.py): `app/core/ingestion_runtime.py`
- [Document preparation](https://github.com/datnguyentrung/ai-receptionist-be-py/tree/main/app/services/ingestion/document): `app/services/ingestion/document`
- [Batch workspace](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/workspace/staged_ingestion.py): `app/services/ingestion/workspace/staged_ingestion.py`
- [Ingestion operations](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/operations.py): `app/services/ingestion/operations.py`
- [Workspace repository](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/repository.py): `app/services/ingestion/repository.py`
- [Neo4j graph store](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/graph_store.py): `app/services/ingestion/graph_store.py`

### GraphRAG

- [Embedding provider](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/graphrag/embeddings.py): `app/services/graphrag/embeddings.py`
- [Graph QA skill](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/skills/graph-qa/tools.py): `app/agent/skills/graph-qa/tools.py`
- [GraphRAG tools](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/agent/tools/graphrag_tools.py): `app/agent/tools/graphrag_tools.py`
- [Knowledge retrieval](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/graphrag/retrieval.py): `app/services/graphrag/retrieval.py`
- **Cited answer**

### Ontology services

- [Ontology management](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ingestion/ontology.py): `app/services/ingestion/ontology.py`
- [Ontology lifecycle](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ontology_lifecycle.py): `app/services/ontology_lifecycle.py`
- [Ontology compiler](https://github.com/datnguyentrung/ai-receptionist-be-py/blob/main/app/services/ontology_compiler.py): `app/services/ontology_compiler.py`

### Other components

- **Image uploader**
- **Ingestion user**

## Connections

- Image uploader → FastAPI application: uploads image
- FastAPI application → Embedding endpoint: routes request (evidence: `app/main.py`)
- Embedding endpoint → Image processing: invokes processing (evidence: `app/api/face_embedding_api.py`)
- Image processing → Face model: detects face (evidence: `app/services/face_embedding_service.py`)
- Image processing → Embedding response: returns vector (evidence: `app/api/face_embedding_api.py`)
- FastAPI application → API error mapping: registers handlers (evidence: `app/main.py`)
- Ingestion user → ADK Web process: uses ingestion UI
- ADK Web process → Runtime container: initializes runtime
- ADK agent → Ingestion skill: loads skill
- Ingestion skill → Ingestion tools: invokes workflow tools
- Ingestion tools → Runtime container: gets services (evidence: `app/agent/tools/ingestion_tools.py`)
- Ingestion tools → Ingestion operations: composes operations (evidence: `app/agent/tools/ingestion_tools.py`)
- Ingestion tools → Batch workspace: manages batches
- Ingestion tools → Workspace repository: persists workspace
- Ingestion tools → Ontology management: uses ontology primitives
- Ingestion tools → Neo4j graph store: fills graph
- Runtime container → Workspace repository: constructs repository (evidence: `app/core/ingestion_runtime.py`)
- Runtime container → Neo4j graph store: constructs graph store (evidence: `app/core/ingestion_runtime.py`)
- Runtime container → Embedding provider: constructs provider (evidence: `app/core/ingestion_runtime.py`)
- Runtime container → Ontology compiler: constructs compiler (evidence: `app/core/ingestion_runtime.py`)
- Runtime container → Ontology lifecycle: constructs lifecycle (evidence: `app/core/ingestion_runtime.py`)
- Ingestion tools → Document preparation: prepares documents
- Graph QA skill → GraphRAG tools: calls retrieval tool
- GraphRAG tools → Knowledge retrieval: invokes retrieval (evidence: `app/agent/tools/graphrag_tools.py`)
- Knowledge retrieval → Neo4j graph store: searches graph (evidence: `app/services/graphrag/retrieval.py`)
- Knowledge retrieval → Embedding provider: uses embeddings (evidence: `app/services/graphrag/retrieval.py`)
- Graph QA skill → Cited answer: returns cited answer
- Ontology management → Ontology lifecycle: supports version lifecycle
- Ontology lifecycle → Ontology compiler: compiles ontology
