# ziyamka2026-art/mka-core architecture

> Architecture diagram of the GitHub repository ziyamka2026-art/mka-core, 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/ziyamka2026-art/mka-core
- Repository: https://github.com/ziyamka2026-art/mka-core

## Overview

MKA is a modular Persian-language tax-knowledge assistant, with a Telegram bot and an admin panel for managing knowledge. The visible query API currently generates answers through the LLM gateway using general model knowledge; its source explicitly says retrieval and real citations are not yet connected. Separately, the repository includes document parsing, embedding, indexing, and semantic-search components. The README names additional planned capabilities, but their implementation is not present in the supplied tree. Arrows below are limited to relationships visible in excerpts, the source index, or README.

Main entry points: [`packages/admin-panel/src/routeTree.gen.ts`](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routeTree.gen.ts) (Route tree), [`packages/google-drive-sync/app/index_local.py`](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/google-drive-sync/app/index_local.py) (Local indexing), [`packages/retrieval-engine/app/query_service.py`](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/retrieval-engine/app/query_service.py) (Semantic query), [`packages/admin-panel/src/routes/auth.tsx`](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/auth.tsx) (Sign in / sign up)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin panel"]
  node_admin_auth["Sign in / sign up<br/>[auth.tsx]"]
  node_auth_guard["Auth guard<br/>[route.tsx]"]
  node_admin_registry["Registry management<br/>[registry-admin.tsx]"]
  node_admin_registry_view["Registry view<br/>[registry.tsx]"]
  node_admin_ask["Ask page<br/>[ask.tsx]"]
  node_admin_circulars["Circulars page<br/>[circulars.tsx]"]
  node_admin_dashboard["Dashboard<br/>[dashboard.tsx]"]
  node_admin_settings["Settings<br/>[settings.tsx]"]
  node_admin_waiver["Waiver tools<br/>[waiver.tsx]"]
  node_route_tree["Route tree<br/>[routeTree.gen.ts]"]
  node_admin_router["Router setup<br/>[router.tsx]"]
end

subgraph group_api["Query API"]
  node_backend_api["RAG API<br/>[main.py]"]
  node_ai_gateway["LLM gateway<br/>[gateway.py]"]
  node_telegram_bot["Telegram bot<br/>[bot.py]"]
end

subgraph group_knowledge["Knowledge pipeline"]
  node_drive_sync["Drive sync"]
  node_local_index["Local indexing<br/>[index_local.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_embedder["Text embeddings<br/>[embedder.py]"]
  node_retrieval_query["Semantic query<br/>[query_service.py]"]
  node_vector_store[("Vector store<br/>[store.py]")]
end

subgraph group_providers["External providers"]
  node_supabase_auth["Supabase auth<br/>[client.ts]"]
  node_llm_provider["LLM provider"]
end

subgraph group_contracts["Shared contracts"]
  node_shared_models["API contracts<br/>[models.py]"]
end

node_operator(("Admin user"))
node_telegram_user(("Telegram user"))

node_operator -->|"signs in"| node_admin_auth
node_admin_auth -->|"authenticates"| node_supabase_auth
node_operator -.->|"manages knowledge"| node_admin_registry
node_operator -.->|"asks questions"| node_admin_ask
node_admin_router -->|"loads routes"| node_route_tree
node_route_tree -->|"registers route"| node_admin_auth
node_route_tree -->|"registers route"| node_admin_registry
node_route_tree -->|"registers route"| node_admin_registry_view
node_route_tree -->|"registers route"| node_admin_ask
node_route_tree -->|"registers route"| node_admin_circulars
node_route_tree -->|"registers route"| node_admin_dashboard
node_route_tree -->|"registers route"| node_admin_settings
node_route_tree -->|"registers route"| node_admin_waiver
node_auth_guard -->|"checks session"| node_supabase_auth
node_telegram_user -->|"messages"| node_telegram_bot
node_backend_api -->|"uses contracts"| node_shared_models
node_backend_api -->|"requests generation"| node_ai_gateway
node_ai_gateway -->|"calls provider"| node_llm_provider
node_local_index -->|"parses documents"| node_parser
node_local_index -->|"generates embeddings"| node_embedder
node_local_index -->|"indexes chunks"| node_vector_store
node_retrieval_query -->|"parses for indexing"| node_parser
node_retrieval_query -->|"creates embedder"| node_embedder
node_retrieval_query -->|"queries store"| node_vector_store
node_vector_store -->|"embeds records"| node_embedder

click node_admin_auth "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/auth.tsx"
click node_auth_guard "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/route.tsx"
click node_admin_registry "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/registry-admin.tsx"
click node_admin_registry_view "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/registry.tsx"
click node_admin_ask "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/ask.tsx"
click node_admin_circulars "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/circulars.tsx"
click node_admin_dashboard "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/dashboard.tsx"
click node_admin_settings "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/settings.tsx"
click node_admin_waiver "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/waiver.tsx"
click node_route_tree "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routeTree.gen.ts"
click node_admin_router "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/router.tsx"
click node_supabase_auth "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/integrations/supabase/client.ts"
click node_backend_api "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/backend-api/app/main.py"
click node_ai_gateway "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/ai-gateway/app/gateway.py"
click node_shared_models "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/shared/mka_shared/models.py"
click node_telegram_bot "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/telegram-bot/app/bot.py"
click node_drive_sync "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/google-drive-sync/app/download_circulars.py"
click node_local_index "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/google-drive-sync/app/index_local.py"
click node_parser "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/document-parser/app/parser.py"
click node_embedder "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/embedding-service/app/embedder.py"
click node_retrieval_query "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/retrieval-engine/app/query_service.py"
click node_vector_store "https://github.com/ziyamka2026-art/mka-core/blob/main/packages/retrieval-engine/app/store.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_admin_auth,node_auth_guard,node_admin_registry,node_admin_registry_view,node_admin_ask,node_admin_circulars,node_admin_dashboard,node_admin_settings,node_admin_waiver,node_route_tree,node_admin_router,node_operator,node_telegram_user toneBlue
class node_backend_api,node_ai_gateway,node_telegram_bot toneAmber
class node_drive_sync,node_local_index,node_parser,node_embedder,node_retrieval_query,node_vector_store toneMint
class node_supabase_auth,node_llm_provider toneRose
class node_shared_models toneIndigo
```

## Components

### Admin panel

- [Sign in / sign up](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/auth.tsx): `packages/admin-panel/src/routes/auth.tsx`
- [Auth guard](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/route.tsx): `packages/admin-panel/src/routes/_authenticated/route.tsx`
- [Registry management](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/registry-admin.tsx): `packages/admin-panel/src/routes/_authenticated/registry-admin.tsx`
- [Registry view](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/registry.tsx): `packages/admin-panel/src/routes/_authenticated/registry.tsx`
- [Ask page](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/ask.tsx): `packages/admin-panel/src/routes/_authenticated/ask.tsx`
- [Circulars page](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/circulars.tsx): `packages/admin-panel/src/routes/_authenticated/circulars.tsx`
- [Dashboard](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/dashboard.tsx): `packages/admin-panel/src/routes/_authenticated/dashboard.tsx`
- [Settings](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/settings.tsx): `packages/admin-panel/src/routes/_authenticated/settings.tsx`
- [Waiver tools](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routes/_authenticated/waiver.tsx): `packages/admin-panel/src/routes/_authenticated/waiver.tsx`
- [Route tree](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/routeTree.gen.ts): `packages/admin-panel/src/routeTree.gen.ts`
- [Router setup](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/router.tsx): `packages/admin-panel/src/router.tsx`

### Query API

- [RAG API](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/backend-api/app/main.py): `packages/backend-api/app/main.py`
- [LLM gateway](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/ai-gateway/app/gateway.py): `packages/ai-gateway/app/gateway.py`
- [Telegram bot](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/telegram-bot/app/bot.py): `packages/telegram-bot/app/bot.py`

### Knowledge pipeline

- [Drive sync](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/google-drive-sync/app/download_circulars.py): `packages/google-drive-sync/app/download_circulars.py`
- [Local indexing](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/google-drive-sync/app/index_local.py): `packages/google-drive-sync/app/index_local.py`
- [Document parser](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/document-parser/app/parser.py): `packages/document-parser/app/parser.py`
- [Text embeddings](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/embedding-service/app/embedder.py): `packages/embedding-service/app/embedder.py`
- [Semantic query](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/retrieval-engine/app/query_service.py): `packages/retrieval-engine/app/query_service.py`
- [Vector store](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/retrieval-engine/app/store.py): `packages/retrieval-engine/app/store.py`

### External providers

- [Supabase auth](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/admin-panel/src/integrations/supabase/client.ts): `packages/admin-panel/src/integrations/supabase/client.ts`
- **LLM provider**

### Shared contracts

- [API contracts](https://github.com/ziyamka2026-art/mka-core/blob/main/packages/shared/mka_shared/models.py): `packages/shared/mka_shared/models.py`

### Other components

- **Admin user**
- **Telegram user**

## Connections

- Admin user → Sign in / sign up: signs in (evidence: `packages/admin-panel/src/routes/auth.tsx`)
- Sign in / sign up → Supabase auth: authenticates (evidence: `packages/admin-panel/src/routes/auth.tsx`)
- Admin user → Registry management: manages knowledge (evidence: `README.md`)
- Admin user → Ask page: asks questions (evidence: `README.md`)
- Router setup → Route tree: loads routes (evidence: `packages/admin-panel/src/router.tsx`)
- Route tree → Sign in / sign up: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Registry management: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Registry view: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Ask page: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Circulars page: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Dashboard: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Settings: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Route tree → Waiver tools: registers route (evidence: `packages/admin-panel/src/routeTree.gen.ts`)
- Auth guard → Supabase auth: checks session (evidence: `packages/admin-panel/src/routes/_authenticated/route.tsx`)
- Telegram user → Telegram bot: messages (evidence: `README.md`)
- RAG API → API contracts: uses contracts (evidence: `packages/backend-api/app/main.py`)
- RAG API → LLM gateway: requests generation (evidence: `packages/backend-api/app/main.py`)
- LLM gateway → LLM provider: calls provider (evidence: `packages/ai-gateway/app/gateway.py`)
- Local indexing → Document parser: parses documents (evidence: `packages/google-drive-sync/app/index_local.py`)
- Local indexing → Text embeddings: generates embeddings (evidence: `packages/google-drive-sync/app/index_local.py`)
- Local indexing → Vector store: indexes chunks (evidence: `packages/google-drive-sync/app/index_local.py`)
- Semantic query → Document parser: parses for indexing (evidence: `packages/retrieval-engine/app/query_service.py`)
- Semantic query → Text embeddings: creates embedder (evidence: `packages/retrieval-engine/app/query_service.py`)
- Semantic query → Vector store: queries store (evidence: `packages/retrieval-engine/app/query_service.py`)
- Vector store → Text embeddings: embeds records (evidence: `packages/retrieval-engine/app/store.py`)
