# ziyamka2026-art/mousavitax-platform architecture

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

## Overview

MousaviTax is an Iranian tax-advice platform combining AI triage, retrieval with citations, tax-specific tools, and human review. The primary user flow is a question submitted in the web Ask page, sent through the API, enriched with knowledge retrieval and optionally an LLM response, then returned with citations. The product also documents tax cases, service discovery, advisors, and human-in-the-loop workflows; unsampled capabilities are represented without asserting unverified runtime links. Source evidence shows the retrieval, embedding, and selected audit-procedure connections; other edges are omitted where wiring was not shown.

Main entry points: [`apps/api/app/main.py`](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/main.py) (API gateway), [`apps/web/src/pages/Ask.tsx`](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/pages/Ask.tsx) (Ask page), [`packages/knowledge-core/knowledge_core/service.py`](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/knowledge-core/knowledge_core/service.py) (Knowledge service), [`packages/embedding-service/app/embedder.py`](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/embedding-service/app/embedder.py) (Text embedder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_ask["Ask page<br/>[Ask.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_citation_list["Citation list<br/>[CitationList.tsx]"]
  node_web_features["Platform pages"]
end

subgraph group_api["API and workflows"]
  node_api_main["API gateway<br/>[main.py]"]
  node_cases["Tax cases<br/>[cases.py]"]
  node_audit_router["Audit procedure API"]
end

subgraph group_knowledge["Knowledge and AI"]
  node_knowledge_service["Knowledge service<br/>[service.py]"]
  node_vector_store[("Vector store<br/>[store.py]")]
  node_embedder["Text embedder<br/>[embedder.py]"]
  node_ai_gateway["LLM gateway<br/>[gateway.py]"]
  node_prompt_parser["APCS parser<br/>[parser.py]"]
  node_prompt_models["Prompt models<br/>[models.py]"]
end

subgraph group_tax["Tax tools"]
  node_audit_engine["Audit procedure rules<br/>[audit_procedure.py]"]
  node_waiver_engine["Waiver calculator<br/>[waiver.py]"]
end

subgraph group_agents["Agent operations"]
  node_agent_orchestrator["Agent router<br/>[orchestrator.py]"]
  node_service_tools["Agent service tools<br/>[service_tools.py]"]
  node_permissions["Permission gate<br/>[permissions.py]"]
  node_audit_logger["Agent audit log<br/>[audit.py]"]
  node_agent_routes["Agent API routes<br/>[agent_routes.py]"]
end

node_taxpayer(("Taxpayer"))
node_llm_provider(("LLM provider"))
node_embedding_provider(("Ollama embeddings"))

node_taxpayer -->|"asks"| node_ask
node_ask -->|"submits question"| node_api_client
node_api_client -->|"HTTP request"| node_api_main
node_ask -->|"renders citations"| node_citation_list
node_api_main -->|"queries knowledge"| node_knowledge_service
node_api_main -->|"generates answer"| node_ai_gateway
node_knowledge_service -->|"queries and indexes"| node_vector_store
node_knowledge_service -->|"creates embeddings"| node_embedder
node_vector_store -->|"embeds queries"| node_embedder
node_ai_gateway -->|"calls provider"| node_llm_provider
node_embedder -->|"requests embeddings"| node_embedding_provider
node_prompt_parser -->|"builds command"| node_prompt_models
node_api_main -->|"imports routes"| node_cases
node_api_main -->|"registers router"| node_audit_router
node_audit_router -->|"calculates procedure"| node_audit_engine
node_api_main -->|"uses waiver rules"| node_waiver_engine
node_service_tools -->|"checks access"| node_permissions
node_service_tools -->|"records actions"| node_audit_logger
node_api_main -.->|"agent endpoint wiring"| node_agent_routes
node_agent_routes -.->|"dispatches requests"| node_agent_orchestrator
node_taxpayer -.->|"uses services and tools"| node_web_features
node_api_main -.->|"serves platform workflows"| node_web_features

click node_ask "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/pages/Ask.tsx"
click node_api_client "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/services/apiClient.ts"
click node_citation_list "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/components/CitationList.tsx"
click node_web_features "https://github.com/ziyamka2026-art/mousavitax-platform/tree/main/apps/web/src/app"
click node_api_main "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/main.py"
click node_cases "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/cases.py"
click node_audit_router "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/audit_procedure_router.py"
click node_knowledge_service "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/knowledge-core/knowledge_core/service.py"
click node_vector_store "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/retrieval-engine/app/store.py"
click node_embedder "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/embedding-service/app/embedder.py"
click node_ai_gateway "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/ai-gateway/app/gateway.py"
click node_prompt_parser "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/prompt-engine/prompt_engine/parser.py"
click node_prompt_models "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/prompt-engine/prompt_engine/models.py"
click node_audit_engine "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/taxlaw-engine/taxlaw_engine/audit_procedure.py"
click node_waiver_engine "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/taxlaw-engine/taxlaw_engine/waiver.py"
click node_agent_orchestrator "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/orchestrator.py"
click node_service_tools "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/service_tools.py"
click node_permissions "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/permissions.py"
click node_audit_logger "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/audit.py"
click node_agent_routes "https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/agent_routes.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_ask,node_api_client,node_citation_list,node_web_features toneBlue
class node_api_main,node_cases,node_audit_router toneAmber
class node_knowledge_service,node_vector_store,node_embedder,node_ai_gateway,node_prompt_parser,node_prompt_models toneMint
class node_audit_engine,node_waiver_engine toneRose
class node_agent_orchestrator,node_service_tools,node_permissions,node_audit_logger,node_agent_routes,node_taxpayer,node_llm_provider,node_embedding_provider toneIndigo
```

## Components

### User interfaces

- [Ask page](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/pages/Ask.tsx): `apps/web/src/pages/Ask.tsx`
- [API client](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/services/apiClient.ts): `apps/web/src/services/apiClient.ts`
- [Citation list](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/web/src/components/CitationList.tsx): `apps/web/src/components/CitationList.tsx`
- [Platform pages](https://github.com/ziyamka2026-art/mousavitax-platform/tree/main/apps/web/src/app): `apps/web/src/app`

### API and workflows

- [API gateway](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Tax cases](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/cases.py): `apps/api/app/cases.py`
- [Audit procedure API](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/audit_procedure_router.py): `apps/api/app/audit_procedure_router.py`

### Knowledge and AI

- [Knowledge service](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/knowledge-core/knowledge_core/service.py): `packages/knowledge-core/knowledge_core/service.py`
- [Vector store](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/retrieval-engine/app/store.py): `packages/retrieval-engine/app/store.py`
- [Text embedder](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/embedding-service/app/embedder.py): `packages/embedding-service/app/embedder.py`
- [LLM gateway](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/ai-gateway/app/gateway.py): `packages/ai-gateway/app/gateway.py`
- [APCS parser](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/prompt-engine/prompt_engine/parser.py): `packages/prompt-engine/prompt_engine/parser.py`
- [Prompt models](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/prompt-engine/prompt_engine/models.py): `packages/prompt-engine/prompt_engine/models.py`

### Tax tools

- [Audit procedure rules](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/taxlaw-engine/taxlaw_engine/audit_procedure.py): `packages/taxlaw-engine/taxlaw_engine/audit_procedure.py`
- [Waiver calculator](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/taxlaw-engine/taxlaw_engine/waiver.py): `packages/taxlaw-engine/taxlaw_engine/waiver.py`

### Agent operations

- [Agent router](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/orchestrator.py): `packages/agent-core/orchestrator.py`
- [Agent service tools](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/service_tools.py): `packages/agent-core/service_tools.py`
- [Permission gate](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/permissions.py): `packages/agent-core/permissions.py`
- [Agent audit log](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/packages/agent-core/audit.py): `packages/agent-core/audit.py`
- [Agent API routes](https://github.com/ziyamka2026-art/mousavitax-platform/blob/main/apps/api/app/agent_routes.py): `apps/api/app/agent_routes.py`

### Other components

- **Taxpayer**
- **LLM provider**
- **Ollama embeddings**

## Connections

- Taxpayer → Ask page: asks (evidence: `apps/web/src/pages/Ask.tsx`)
- Ask page → API client: submits question (evidence: `apps/web/src/pages/Ask.tsx`)
- API client → API gateway: HTTP request (evidence: `apps/web/src/services/apiClient.ts`)
- Ask page → Citation list: renders citations (evidence: `apps/web/src/pages/Ask.tsx`)
- API gateway → Knowledge service: queries knowledge (evidence: `apps/api/app/main.py`)
- API gateway → LLM gateway: generates answer (evidence: `apps/api/app/main.py`)
- Knowledge service → Vector store: queries and indexes (evidence: `packages/knowledge-core/knowledge_core/service.py`)
- Knowledge service → Text embedder: creates embeddings (evidence: `packages/knowledge-core/knowledge_core/service.py`)
- Vector store → Text embedder: embeds queries (evidence: `packages/retrieval-engine/app/store.py`)
- LLM gateway → LLM provider: calls provider (evidence: `packages/ai-gateway/app/gateway.py`)
- Text embedder → Ollama embeddings: requests embeddings (evidence: `packages/embedding-service/app/embedder.py`)
- APCS parser → Prompt models: builds command (evidence: `packages/prompt-engine/prompt_engine/parser.py`)
- API gateway → Tax cases: imports routes (evidence: `apps/api/app/main.py`)
- API gateway → Audit procedure API: registers router (evidence: `apps/api/app/main.py`)
- Audit procedure API → Audit procedure rules: calculates procedure (evidence: `apps/api/app/audit_procedure_router.py`)
- API gateway → Waiver calculator: uses waiver rules (evidence: `apps/api/app/main.py`)
- Agent service tools → Permission gate: checks access (evidence: `packages/agent-core/service_tools.py`)
- Agent service tools → Agent audit log: records actions (evidence: `packages/agent-core/service_tools.py`)
- API gateway → Agent API routes: agent endpoint wiring
- Agent API routes → Agent router: dispatches requests
- Taxpayer → Platform pages: uses services and tools
- API gateway → Platform pages: serves platform workflows
