# apache/answer architecture

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

- Interactive diagram: https://gitdiagram.com/apache/answer
- Repository: https://github.com/apache/answer

## Overview

#### Purpose and Runtime
Apache Answer is a self-hosted Q&A, help-center, and knowledge-management platform. It ships as a Go backend plus React frontend, typically packaged in a Docker image and deployed with persistent `/data` storage. Primary runtime/build entry points are `cmd/main.go`, `cmd/command.go`, and `cmd/wire_gen.go`; container startup is defined by `Dockerfile` and `script/entrypoint.sh`.

#### Application Composition and Startup
The Go executable uses Cobra commands and Google Wire-generated dependency injection. Startup assembles configuration, repositories, services, HTTP server, scheduled work, and routes through provider modules rather than a single monolith initializer. Installation is a first-class server mode that can bootstrap configuration from environment values.
- `cmd/main.go`
- `cmd/wire.go`
- `internal/install/install_server.go`

#### HTTP, UI, and API Boundary
The backend hosts API, static/UI, Swagger, template-rendered, plugin, and MCP endpoints. Requests pass through shared middleware for recovery, authentication, API keys, language, rate limiting, and specialized plugin/MCP access controls before controllers invoke services. The React SPA is the principal interactive client; server HTML templates support rendered/public pages and SEO-oriented views.
- `internal/base/server/http.go`
- `internal/router/config.go`
- `internal/router/mcp_router.go`
- `ui/src/router/routes.ts`
- `ui/static.go`

#### Core Domain and Layering
Domain operations follow a controller → service → repository → entity pattern. Controllers expose public/admin workflows; services enforce content, permissions, revisions, reviews, voting, tags, collections, badges, notifications, and user/account policies; repositories persist and query entities. API schemas form the request/response boundary, distinct from persistence entities.
- `internal/controller/question_controller.go`
- `internal/service/content/question_service.go`
- `internal/repo/question/question_repo.go`
- `internal/entity/question_entity.go`
- `internal/schema/question_schema.go`

#### Persistence, Installation, and Configuration
Persistent state includes users/authentication, questions/answers/comments, tags, revisions, reviews, notifications, plugin configuration/KV data, API keys, and site configuration. Versioned migrations initialize and evolve the schema; installation can be driven interactively or from environment settings. Configuration defaults and runtime loading are centralized outside individual features.
- `configs/config.yaml`
- `configs/config.go`
- `internal/migrations/migrations.go`
- `internal/migrations/init_data.go`
- `internal/base/conf/conf.go`

#### Asynchronous and Derived Work
In-process queue abstractions and cron support decouple side effects from request handling: activity tracking, event processing, notification/email delivery, search indexing, and vector/embedding synchronization. This is a material boundary for changes that create content or user events: synchronous domain writes can trigger downstream queue/event work.
- `internal/base/queue/queue.go`
- `internal/base/cron/cron.go`
- `internal/service/eventqueue/event_queue.go`
- `internal/service/notification/notification_service.go`
- `internal/service/vector_sync/vector_sync.go`

#### Extensibility and External Integrations
A typed plugin contract exposes replaceable or additive capabilities including authentication/user center, CAPTCHA, CDN/storage/upload, search/vector search, parsers/rendering, connectors/importers, review, filtering, notifications, and plugin KV storage. AI conversations, embeddings, and MCP routes provide AI-agent-facing integration points. Implementations can therefore cross external boundaries without embedding provider-specific logic into core content services.
- `plugin/plugin.go`
- `plugin/search.go`
- `plugin/vector_search.go`
- `internal/service/ai_conversation/ai_conversation_service.go`
- `internal/controller/mcp_controller.go`

#### Deployment and Frontend Delivery
The frontend is a React/TypeScript application with route-level public, user, review, install, and administration surfaces; its service clients call backend APIs. Docker Compose and Helm provide local and Kubernetes deployment paths, with deployment, service, ingress, PVC, and autoscaling manifests.
- `ui/src/index.tsx`
- `ui/src/services/index.ts`
- `docker-compose.yaml`
- `charts/templates/deployment.yaml`
- `charts/templates/pvc.yaml`

Main entry points: [`cmd/main.go`](https://github.com/apache/answer/blob/main/cmd/main.go) (Go application), [`internal/router/config.go`](https://github.com/apache/answer/blob/main/internal/router/config.go) (API, UI & MCP routes), [`internal/service/content/question_service.go`](https://github.com/apache/answer/blob/main/internal/service/content/question_service.go) (Domain services), [`internal/service/eventqueue/event_queue.go`](https://github.com/apache/answer/blob/main/internal/service/eventqueue/event_queue.go) (Event queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup &amp; Configuration"]
  node_go_app{{"Go application<br/>Cobra + Wire<br/>[main.go]"}}
  node_install["Install server<br/>bootstrap mode<br/>[install_server.go]"]
  node_runtime_config["Runtime configuration<br/>[conf.go]"]
  node_migrations[("Migrations &amp; seed data<br/>schema evolution<br/>[migrations.go]")]
end

subgraph group_delivery["HTTP &amp; Frontend"]
  node_http_server["HTTP server &amp; middleware<br/>Go HTTP boundary<br/>[http.go]"]
  node_routes["API, UI &amp; MCP routes<br/>router<br/>[config.go]"]
  node_controllers["Controllers<br/>workflow handlers"]
  node_react_ui["React SPA<br/>TypeScript client<br/>[index.tsx]"]
  node_ui_clients["Frontend service clients<br/>API client layer<br/>[index.ts]"]
  node_server_ui["Static UI &amp; templates<br/>server-rendered delivery<br/>[static.go]"]
end

subgraph group_domain["Core Domain"]
  node_domain_services["Domain services<br/>business rules"]
  node_schemas["API schemas<br/>request/response models<br/>[question_schema.go]"]
  node_repositories["Repositories<br/>persistence access<br/>[question_repo.go]"]
  node_entities[("Persistence entities<br/>data models<br/>[question_entity.go]")]
end

subgraph group_async["Async Work"]
  node_event_queue["Event queue<br/>in-process async dispatch<br/>[event_queue.go]"]
  node_scheduled_work["Cron scheduler<br/>scheduled jobs<br/>[cron.go]"]
  node_notifications["Notification delivery<br/>async service"]
  node_vector_sync["Vector synchronization<br/>derived indexing<br/>[vector_sync.go]"]
end

subgraph group_extensions["Extensions &amp; AI"]
  node_plugin_contract["Plugin contracts<br/>typed extension boundary<br/>[plugin.go]"]
  node_ai_mcp["AI conversations &amp; MCP<br/>AI integration"]
end

subgraph group_deploy["Deployment"]
  node_container["Container runtime<br/>Docker image"]
  node_kubernetes["Kubernetes deployment<br/>Helm workload<br/>[deployment.yaml]"]
end

node_container -->|"starts"| node_go_app
node_kubernetes -->|"runs image"| node_container
node_go_app -->|"loads"| node_runtime_config
node_go_app -->|"serves install mode"| node_install
node_install -->|"initializes"| node_migrations
node_go_app -->|"applies"| node_migrations
node_go_app -->|"assembles"| node_http_server
node_http_server -->|"dispatches"| node_routes
node_routes -->|"maps requests"| node_controllers
node_routes -->|"serves"| node_server_ui
node_react_ui -->|"uses"| node_ui_clients
node_ui_clients -->|"calls APIs"| node_http_server
node_controllers -->|"binds"| node_schemas
node_controllers -->|"invokes"| node_domain_services
node_domain_services -->|"persists through"| node_repositories
node_repositories -->|"maps"| node_entities
node_domain_services -->|"publishes side effects"| node_event_queue
node_event_queue -->|"delivers"| node_notifications
node_event_queue -->|"indexes"| node_vector_sync
node_scheduled_work -->|"triggers jobs"| node_event_queue
node_domain_services -->|"uses capabilities"| node_plugin_contract
node_routes -->|"exposes AI/MCP"| node_ai_mcp
node_ai_mcp -->|"uses providers"| node_plugin_contract

click node_go_app "https://github.com/apache/answer/blob/main/cmd/main.go"
click node_install "https://github.com/apache/answer/blob/main/internal/install/install_server.go"
click node_runtime_config "https://github.com/apache/answer/blob/main/internal/base/conf/conf.go"
click node_migrations "https://github.com/apache/answer/blob/main/internal/migrations/migrations.go"
click node_http_server "https://github.com/apache/answer/blob/main/internal/base/server/http.go"
click node_routes "https://github.com/apache/answer/blob/main/internal/router/config.go"
click node_controllers "https://github.com/apache/answer/blob/main/internal/controller/question_controller.go"
click node_react_ui "https://github.com/apache/answer/blob/main/ui/src/index.tsx"
click node_ui_clients "https://github.com/apache/answer/blob/main/ui/src/services/index.ts"
click node_server_ui "https://github.com/apache/answer/blob/main/ui/static.go"
click node_domain_services "https://github.com/apache/answer/blob/main/internal/service/content/question_service.go"
click node_schemas "https://github.com/apache/answer/blob/main/internal/schema/question_schema.go"
click node_repositories "https://github.com/apache/answer/blob/main/internal/repo/question/question_repo.go"
click node_entities "https://github.com/apache/answer/blob/main/internal/entity/question_entity.go"
click node_event_queue "https://github.com/apache/answer/blob/main/internal/service/eventqueue/event_queue.go"
click node_scheduled_work "https://github.com/apache/answer/blob/main/internal/base/cron/cron.go"
click node_notifications "https://github.com/apache/answer/blob/main/internal/service/notification/notification_service.go"
click node_vector_sync "https://github.com/apache/answer/blob/main/internal/service/vector_sync/vector_sync.go"
click node_plugin_contract "https://github.com/apache/answer/blob/main/plugin/plugin.go"
click node_ai_mcp "https://github.com/apache/answer/blob/main/internal/service/ai_conversation/ai_conversation_service.go"
click node_container "https://github.com/apache/answer/blob/main/Dockerfile"
click node_kubernetes "https://github.com/apache/answer/blob/main/charts/templates/deployment.yaml"

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_go_app,node_install,node_runtime_config,node_migrations toneBlue
class node_http_server,node_routes,node_controllers,node_react_ui,node_ui_clients,node_server_ui toneAmber
class node_domain_services,node_schemas,node_repositories,node_entities toneMint
class node_event_queue,node_scheduled_work,node_notifications,node_vector_sync toneRose
class node_plugin_contract,node_ai_mcp toneIndigo
class node_container,node_kubernetes toneTeal
```

## Components

### Startup & Configuration

- [Go application](https://github.com/apache/answer/blob/main/cmd/main.go): Cobra + Wire · Builds server modes and dependency graph. · `cmd/main.go`
- [Install server](https://github.com/apache/answer/blob/main/internal/install/install_server.go): bootstrap mode · Initializes configuration from interactive or environment input. · `internal/install/install_server.go`
- [Runtime configuration](https://github.com/apache/answer/blob/main/internal/base/conf/conf.go): configuration · `internal/base/conf/conf.go`
- [Migrations & seed data](https://github.com/apache/answer/blob/main/internal/migrations/migrations.go): schema evolution · `internal/migrations/migrations.go`

### HTTP & Frontend

- [HTTP server & middleware](https://github.com/apache/answer/blob/main/internal/base/server/http.go): Go HTTP boundary · Applies authentication, rate limits, language, recovery, and access controls. · `internal/base/server/http.go`
- [API, UI & MCP routes](https://github.com/apache/answer/blob/main/internal/router/config.go): router · `internal/router/config.go`
- [Controllers](https://github.com/apache/answer/blob/main/internal/controller/question_controller.go): workflow handlers · Public and administration endpoints invoke domain operations. · `internal/controller/question_controller.go`
- [React SPA](https://github.com/apache/answer/blob/main/ui/src/index.tsx): TypeScript client · `ui/src/index.tsx`
- [Frontend service clients](https://github.com/apache/answer/blob/main/ui/src/services/index.ts): API client layer · `ui/src/services/index.ts`
- [Static UI & templates](https://github.com/apache/answer/blob/main/ui/static.go): server-rendered delivery · Hosts SPA assets and rendered public pages. · `ui/static.go`

### Core Domain

- [Domain services](https://github.com/apache/answer/blob/main/internal/service/content/question_service.go): business rules · Content, permissions, revisions, reviews, voting, tags, and account policies. · `internal/service/content/question_service.go`
- [API schemas](https://github.com/apache/answer/blob/main/internal/schema/question_schema.go): request/response models · `internal/schema/question_schema.go`
- [Repositories](https://github.com/apache/answer/blob/main/internal/repo/question/question_repo.go): persistence access · `internal/repo/question/question_repo.go`
- [Persistence entities](https://github.com/apache/answer/blob/main/internal/entity/question_entity.go): data models · `internal/entity/question_entity.go`

### Async Work

- [Event queue](https://github.com/apache/answer/blob/main/internal/service/eventqueue/event_queue.go): in-process async dispatch · Decouples side effects from synchronous domain writes. · `internal/service/eventqueue/event_queue.go`
- [Cron scheduler](https://github.com/apache/answer/blob/main/internal/base/cron/cron.go): scheduled jobs · `internal/base/cron/cron.go`
- [Notification delivery](https://github.com/apache/answer/blob/main/internal/service/notification/notification_service.go): async service · `internal/service/notification/notification_service.go`
- [Vector synchronization](https://github.com/apache/answer/blob/main/internal/service/vector_sync/vector_sync.go): derived indexing · `internal/service/vector_sync/vector_sync.go`

### Extensions & AI

- [Plugin contracts](https://github.com/apache/answer/blob/main/plugin/plugin.go): typed extension boundary · Allows provider-specific auth, storage, search, rendering, and integrations. · `plugin/plugin.go`
- [AI conversations & MCP](https://github.com/apache/answer/blob/main/internal/service/ai_conversation/ai_conversation_service.go): AI integration · `internal/service/ai_conversation/ai_conversation_service.go`

### Deployment

- [Container runtime](https://github.com/apache/answer/blob/main/Dockerfile): Docker image · Starts the application with persistent data storage. · `Dockerfile`
- [Kubernetes deployment](https://github.com/apache/answer/blob/main/charts/templates/deployment.yaml): Helm workload · Deployment is paired with persistent-volume manifests. · `charts/templates/deployment.yaml`

## Connections

- Container runtime → Go application: starts
- Kubernetes deployment → Container runtime: runs image
- Go application → Runtime configuration: loads
- Go application → Install server: serves install mode
- Install server → Migrations & seed data: initializes
- Go application → Migrations & seed data: applies
- Go application → HTTP server & middleware: assembles
- HTTP server & middleware → API, UI & MCP routes: dispatches
- API, UI & MCP routes → Controllers: maps requests
- API, UI & MCP routes → Static UI & templates: serves
- React SPA → Frontend service clients: uses
- Frontend service clients → HTTP server & middleware: calls APIs
- Controllers → API schemas: binds
- Controllers → Domain services: invokes
- Domain services → Repositories: persists through
- Repositories → Persistence entities: maps
- Domain services → Event queue: publishes side effects
- Event queue → Notification delivery: delivers
- Event queue → Vector synchronization: indexes
- Cron scheduler → Event queue: triggers jobs
- Domain services → Plugin contracts: uses capabilities
- API, UI & MCP routes → AI conversations & MCP: exposes AI/MCP
- AI conversations & MCP → Plugin contracts: uses providers
