# scorpio-meow/askmiao architecture

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

- Interactive diagram: https://gitdiagram.com/scorpio-meow/askmiao
- Repository: https://github.com/scorpio-meow/askmiao

## Overview

AskMiao is an enterprise knowledge-chat application: users ask questions, an Agent researches the knowledge base and optional external sources, and streamed answers expose citations and research steps. Administrators manage documents and external tools; authentication gates both workflows. The README documents major capabilities beyond the sampled excerpts, so their modules are included by exact paths, while uncertain internal call wiring is omitted. The sampled RAG manager, pipeline, LLM client, database setup, and MCP client establish selected internal layers and integrations.

Main entry points: [`backend/app/rag/contextual_rag.py`](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/contextual_rag.py) (Contextual RAG), [`backend/app/api/chat.py`](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/chat.py) (Chat routes), [`backend/app/models/database.py`](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/models/database.py) (Application database), [`frontend/src/App.jsx`](https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/App.jsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_authui["Authentication UI<br/>[authService.ts]"]
  node_chatui["Chat interface<br/>[index.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_chat_api["Chat routes<br/>[chat.py]"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_database[("Application database<br/>[database.py]")]
end

subgraph group_research["Research and retrieval"]
  node_rag_manager["RAG manager<br/>[rag_manager.py]"]
  node_pipeline["Research pipeline<br/>[pipeline.py]"]
  node_agent["Research agent<br/>[agent.py]"]
  node_tools["Research tools<br/>[tools.py]"]
  node_retriever["Hybrid retrieval<br/>[hybrid.py]"]
  node_contextual_rag["Contextual RAG<br/>[contextual_rag.py]"]
  node_vector_store[("Vector index<br/>[vector_store.py]")]
  node_bm25_store[("BM25 index<br/>[bm25_store.py]")]
  node_chunk_store[("Chunk store<br/>[chunk_store.py]")]
  node_llm["LLM providers<br/>[llm_client.py]"]
end

subgraph group_knowledge["Knowledge management"]
  node_documents_api["Document routes<br/>[documents.py]"]
  node_document_processor["Document processing"]
  node_pdf_service["PDF extraction<br/>[pdf_service.py]"]
end

subgraph group_integrations["External tools"]
  node_admin_tools_api["API tool management<br/>[api_tools.py]"]
  node_openapi_parser["OpenAPI import<br/>[openapi_parser.py]"]
  node_mcp_api["MCP management<br/>[mcp.py]"]
  node_mcp_service["MCP client<br/>[mcp_service.py]"]
  node_approval["Tool approval<br/>[tool_approval.py]"]
  node_web_services["Web search and fetch<br/>[tools.py]"]
end

node_user(("User"))
node_llm_provider(("Model services"))
node_mcp_servers(("MCP servers"))
node_web(("Web sources"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authui
node_webapp -->|"routes to"| node_chatui
node_authui -->|"requests"| node_api_client
node_chatui -->|"sends chat"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"dispatches"| node_auth_api
node_backend -->|"dispatches"| node_chat_api
node_auth_api -->|"checks accounts"| node_database
node_chat_api -->|"handles chat"| node_chat_service
node_chat_service -->|"gets RAG system"| node_rag_manager
node_rag_manager -->|"creates"| node_contextual_rag
node_contextual_rag -->|"opens sessions"| node_database
node_pipeline -->|"streams research"| node_agent
node_pipeline -->|"creates registry"| node_tools
node_tools -->|"searches knowledge"| node_retriever
node_agent -->|"requests model"| node_llm
node_llm -->|"calls provider"| node_llm_provider
node_retriever -->|"vector search"| node_vector_store
node_retriever -->|"keyword search"| node_bm25_store
node_contextual_rag -->|"loads chunks"| node_chunk_store
node_contextual_rag -->|"aligns index"| node_vector_store
node_contextual_rag -->|"aligns index"| node_bm25_store
node_chat_api -->|"streams events"| node_user
node_documents_api -->|"processes uploads"| node_document_processor
node_document_processor -->|"extracts PDFs"| node_pdf_service
node_document_processor -->|"indexes chunks"| node_contextual_rag
node_documents_api -->|"manages documents"| node_database
node_admin_tools_api -->|"imports specs"| node_openapi_parser
node_admin_tools_api -->|"stores tool config"| node_database
node_mcp_api -->|"manages connections"| node_mcp_service
node_mcp_service -->|"discovers and calls"| node_mcp_servers
node_agent -->|"requests approval"| node_approval
node_approval -->|"resolves through API"| node_chat_api
node_tools -->|"provides tools"| node_web_services
node_web_services -.->|"searches or fetches"| node_web

click node_webapp "https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/App.jsx"
click node_authui "https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/services/authService.ts"
click node_chatui "https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/pages/Chat/index.tsx"
click node_api_client "https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/services/api.ts"
click node_backend "https://github.com/scorpio-meow/askmiao/blob/New/backend/main.py"
click node_auth_api "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/auth.py"
click node_chat_api "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/chat.py"
click node_chat_service "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/chat_service.py"
click node_database "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/models/database.py"
click node_rag_manager "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/core/rag_manager.py"
click node_pipeline "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/pipeline.py"
click node_agent "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/agent.py"
click node_tools "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/tools.py"
click node_retriever "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/retrievers/hybrid.py"
click node_contextual_rag "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/contextual_rag.py"
click node_vector_store "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/indices/vector_store.py"
click node_bm25_store "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/indices/bm25_store.py"
click node_chunk_store "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/indices/chunk_store.py"
click node_llm "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/core/llm_client.py"
click node_documents_api "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/documents.py"
click node_document_processor "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/document_processor.py"
click node_pdf_service "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/pdf_service.py"
click node_admin_tools_api "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/api_tools.py"
click node_openapi_parser "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/openapi_parser.py"
click node_mcp_api "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/mcp.py"
click node_mcp_service "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/mcp_service.py"
click node_approval "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/tool_approval.py"
click node_web_services "https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/tools.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_webapp,node_authui,node_chatui,node_api_client,node_user toneBlue
class node_backend,node_auth_api,node_chat_api,node_chat_service,node_database toneAmber
class node_rag_manager,node_pipeline,node_agent,node_tools,node_retriever,node_contextual_rag,node_vector_store,node_bm25_store,node_chunk_store,node_llm,node_mcp_servers toneMint
class node_documents_api,node_document_processor,node_pdf_service toneRose
class node_admin_tools_api,node_openapi_parser,node_mcp_api,node_mcp_service,node_approval,node_web_services,node_llm_provider,node_web toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Authentication UI](https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Chat interface](https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/pages/Chat/index.tsx): `frontend/src/pages/Chat/index.tsx`
- [API client](https://github.com/scorpio-meow/askmiao/blob/New/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and identity

- [FastAPI application](https://github.com/scorpio-meow/askmiao/blob/New/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Chat routes](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Chat service](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [Application database](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/models/database.py): `backend/app/models/database.py`

### Research and retrieval

- [RAG manager](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/core/rag_manager.py): `backend/app/core/rag_manager.py`
- [Research pipeline](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/pipeline.py): `backend/app/rag/pipeline.py`
- [Research agent](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/agent.py): `backend/app/rag/agent.py`
- [Research tools](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/tools.py): `backend/app/rag/tools.py`
- [Hybrid retrieval](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/retrievers/hybrid.py): `backend/app/rag/retrievers/hybrid.py`
- [Contextual RAG](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/contextual_rag.py): `backend/app/rag/contextual_rag.py`
- [Vector index](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/indices/vector_store.py): `backend/app/rag/indices/vector_store.py`
- [BM25 index](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/indices/bm25_store.py): `backend/app/rag/indices/bm25_store.py`
- [Chunk store](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/indices/chunk_store.py): `backend/app/rag/indices/chunk_store.py`
- [LLM providers](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/core/llm_client.py): `backend/app/core/llm_client.py`

### Knowledge management

- [Document routes](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Document processing](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/document_processor.py): `backend/app/services/document_processor.py`
- [PDF extraction](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`

### External tools

- [API tool management](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/api_tools.py): `backend/app/api/api_tools.py`
- [OpenAPI import](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/openapi_parser.py): `backend/app/services/openapi_parser.py`
- [MCP management](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/api/mcp.py): `backend/app/api/mcp.py`
- [MCP client](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/services/mcp_service.py): `backend/app/services/mcp_service.py`
- [Tool approval](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/tool_approval.py): `backend/app/rag/tool_approval.py`
- [Web search and fetch](https://github.com/scorpio-meow/askmiao/blob/New/backend/app/rag/tools.py): `backend/app/rag/tools.py`

### Other components

- **User**
- **Model services**
- **MCP servers**
- **Web sources**

## Connections

- User → Web application: uses
- Web application → Authentication UI: routes to
- Web application → Chat interface: routes to
- Authentication UI → API client: requests
- Chat interface → API client: sends chat
- API client → FastAPI application: calls API
- FastAPI application → Authentication routes: dispatches
- FastAPI application → Chat routes: dispatches
- Authentication routes → Application database: checks accounts
- Chat routes → Chat service: handles chat
- Chat service → RAG manager: gets RAG system
- RAG manager → Contextual RAG: creates
- Contextual RAG → Application database: opens sessions
- Research pipeline → Research agent: streams research
- Research pipeline → Research tools: creates registry
- Research tools → Hybrid retrieval: searches knowledge
- Research agent → LLM providers: requests model
- LLM providers → Model services: calls provider
- Hybrid retrieval → Vector index: vector search
- Hybrid retrieval → BM25 index: keyword search
- Contextual RAG → Chunk store: loads chunks
- Contextual RAG → Vector index: aligns index
- Contextual RAG → BM25 index: aligns index
- Chat routes → User: streams events
- Document routes → Document processing: processes uploads
- Document processing → PDF extraction: extracts PDFs
- Document processing → Contextual RAG: indexes chunks
- Document routes → Application database: manages documents
- API tool management → OpenAPI import: imports specs
- API tool management → Application database: stores tool config
- MCP management → MCP client: manages connections
- MCP client → MCP servers: discovers and calls
- Research agent → Tool approval: requests approval
- Tool approval → Chat routes: resolves through API
- Research tools → Web search and fetch: provides tools
- Web search and fetch → Web sources: searches or fetches