# yayasan-digital-islami-indonesia/quran-api-go architecture

> Architecture diagram of the GitHub repository yayasan-digital-islami-indonesia/quran-api-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yayasan-digital-islami-indonesia/quran-api-go
- Repository: https://github.com/yayasan-digital-islami-indonesia/quran-api-go

## Overview

Quran API Go serves Quran text, translations, surah/juz metadata, and full-text search through REST and MCP interfaces. The main request flow is an HTTP client or MCP client calling its respective server entry point, which delegates to feature services and repositories backed by SQLite. The README documents capabilities beyond the sampled implementation excerpts; those are represented at subsystem level. Wiring is visible in the API entry point, while only search and MCP service calls are directly shown in the excerpts.

Main entry points: [`cmd/api/main.go`](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/cmd/api/main.go) (REST API), [`internal/mcpserver/server.go`](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/mcpserver/server.go) (MCP tools), [`internal/service/search_service.go`](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/search_service.go) (Search service), [`internal/repository/search_repository.go`](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/search_repository.go) (Search repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entry points"]
  node_api["REST API<br/>[main.go]"]
  node_mcp["MCP tools<br/>[server.go]"]
end

subgraph group_content["Quran content"]
  node_ayah_handler["Ayah routes<br/>[ayah_handler.go]"]
  node_ayah_service["Ayah service<br/>[ayah_service.go]"]
  node_ayah_repo["Ayah repository<br/>[ayah_repository.go]"]
  node_surah_handler["Surah routes<br/>[surah_handler.go]"]
  node_surah_service["Surah service<br/>[surah_service.go]"]
  node_surah_repo["Surah repository"]
  node_juz_handler["Juz routes<br/>[juz_handler.go]"]
  node_juz_service["Juz service<br/>[juz_service.go]"]
  node_juz_repo["Juz repository<br/>[juz_repository.go]"]
end

subgraph group_lookup["Search and status"]
  node_search_handler["Search route<br/>[search_handler.go]"]
  node_search_service["Search service<br/>[search_service.go]"]
  node_search_repo["Search repository"]
  node_health_handler["Health routes"]
  node_health_service["Health service"]
  node_health_repo["Health repository"]
end

subgraph group_storage["Data access"]
  node_sqlite[("SQLite database<br/>[database.go]")]
end

node_http_client(("HTTP client"))
node_mcp_client(("MCP client"))

node_http_client -->|"calls"| node_api
node_mcp_client -->|"calls"| node_mcp
node_api -->|"routes"| node_ayah_handler
node_api -->|"routes"| node_surah_handler
node_api -->|"routes"| node_juz_handler
node_api -->|"routes"| node_search_handler
node_api -->|"routes"| node_health_handler
node_api -->|"mounts"| node_mcp
node_api -->|"opens"| node_sqlite
node_api -->|"wires"| node_ayah_repo
node_api -->|"wires"| node_surah_repo
node_api -->|"wires"| node_juz_repo
node_api -->|"wires"| node_search_repo
node_api -->|"wires"| node_health_repo
node_api -->|"wires"| node_ayah_service
node_api -->|"wires"| node_surah_service
node_api -->|"wires"| node_juz_service
node_api -->|"wires"| node_search_service
node_api -->|"wires"| node_health_service
node_mcp -->|"calls"| node_ayah_service
node_mcp -->|"calls"| node_surah_service
node_mcp -->|"calls"| node_juz_service
node_mcp -->|"calls"| node_search_service
node_search_handler -->|"calls"| node_search_service
node_search_service -->|"delegates"| node_search_repo
node_search_repo -->|"queries"| node_sqlite
node_ayah_repo -->|"queries"| node_sqlite

click node_api "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/cmd/api/main.go"
click node_mcp "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/mcpserver/server.go"
click node_ayah_handler "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/ayah_handler.go"
click node_ayah_service "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/ayah_service.go"
click node_ayah_repo "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/ayah_repository.go"
click node_surah_handler "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/surah_handler.go"
click node_surah_service "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/surah_service.go"
click node_surah_repo "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/surah_repository.go"
click node_juz_handler "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/juz_handler.go"
click node_juz_service "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/juz_service.go"
click node_juz_repo "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/juz_repository.go"
click node_search_handler "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/search_handler.go"
click node_search_service "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/search_service.go"
click node_search_repo "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/search_repository.go"
click node_health_handler "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/healthcheck_handler.go"
click node_health_service "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/healthcheck_service.go"
click node_health_repo "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/healthcheck_repository.go"
click node_sqlite "https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/database/database.go"

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_api,node_mcp,node_http_client,node_mcp_client toneBlue
class node_ayah_handler,node_ayah_service,node_ayah_repo,node_surah_handler,node_surah_service,node_surah_repo,node_juz_handler,node_juz_service,node_juz_repo toneAmber
class node_search_handler,node_search_service,node_search_repo,node_health_handler,node_health_service,node_health_repo toneMint
class node_sqlite toneRose
```

## Components

### Product entry points

- [REST API](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [MCP tools](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/mcpserver/server.go): `internal/mcpserver/server.go`

### Quran content

- [Ayah routes](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/ayah_handler.go): `internal/handler/ayah_handler.go`
- [Ayah service](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/ayah_service.go): `internal/service/ayah_service.go`
- [Ayah repository](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/ayah_repository.go): `internal/repository/ayah_repository.go`
- [Surah routes](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/surah_handler.go): `internal/handler/surah_handler.go`
- [Surah service](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/surah_service.go): `internal/service/surah_service.go`
- [Surah repository](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/surah_repository.go): `internal/repository/surah_repository.go`
- [Juz routes](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/juz_handler.go): `internal/handler/juz_handler.go`
- [Juz service](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/juz_service.go): `internal/service/juz_service.go`
- [Juz repository](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/juz_repository.go): `internal/repository/juz_repository.go`

### Search and status

- [Search route](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/search_handler.go): `internal/handler/search_handler.go`
- [Search service](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/search_service.go): `internal/service/search_service.go`
- [Search repository](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/search_repository.go): `internal/repository/search_repository.go`
- [Health routes](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/handler/healthcheck_handler.go): `internal/handler/healthcheck_handler.go`
- [Health service](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/service/healthcheck_service.go): `internal/service/healthcheck_service.go`
- [Health repository](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/repository/healthcheck_repository.go): `internal/repository/healthcheck_repository.go`

### Data access

- [SQLite database](https://github.com/yayasan-digital-islami-indonesia/quran-api-go/blob/main/internal/database/database.go): `internal/database/database.go`

### Other components

- **HTTP client**
- **MCP client**

## Connections

- HTTP client → REST API: calls
- MCP client → MCP tools: calls
- REST API → Ayah routes: routes (evidence: `cmd/api/main.go`)
- REST API → Surah routes: routes (evidence: `cmd/api/main.go`)
- REST API → Juz routes: routes (evidence: `cmd/api/main.go`)
- REST API → Search route: routes (evidence: `cmd/api/main.go`)
- REST API → Health routes: routes (evidence: `cmd/api/main.go`)
- REST API → MCP tools: mounts (evidence: `cmd/api/main.go`)
- REST API → SQLite database: opens (evidence: `cmd/api/main.go`)
- REST API → Ayah repository: wires (evidence: `cmd/api/main.go`)
- REST API → Surah repository: wires (evidence: `cmd/api/main.go`)
- REST API → Juz repository: wires (evidence: `cmd/api/main.go`)
- REST API → Search repository: wires (evidence: `cmd/api/main.go`)
- REST API → Health repository: wires (evidence: `cmd/api/main.go`)
- REST API → Ayah service: wires (evidence: `cmd/api/main.go`)
- REST API → Surah service: wires (evidence: `cmd/api/main.go`)
- REST API → Juz service: wires (evidence: `cmd/api/main.go`)
- REST API → Search service: wires (evidence: `cmd/api/main.go`)
- REST API → Health service: wires (evidence: `cmd/api/main.go`)
- MCP tools → Ayah service: calls (evidence: `internal/mcpserver/server.go`)
- MCP tools → Surah service: calls (evidence: `internal/mcpserver/server.go`)
- MCP tools → Juz service: calls (evidence: `internal/mcpserver/server.go`)
- MCP tools → Search service: calls (evidence: `internal/mcpserver/server.go`)
- Search route → Search service: calls (evidence: `internal/handler/search_handler.go`)
- Search service → Search repository: delegates (evidence: `internal/service/search_service.go`)
- Search repository → SQLite database: queries (evidence: `internal/repository/search_repository.go`)
- Ayah repository → SQLite database: queries (evidence: `internal/repository/ayah_repository.go`)
