Apache Answer

# MISSION: Scaffold "Apache Answer" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Apache Answer**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Apache Answer
- **What It Does**: Apache Answer is an open-source Q&A platform for communities, help centers and internal knowledge bases, delivered as a single Go binary with an embedded React UI and a Go plugin system.
- **Domain & Category**: Q&A & Developer Knowledge Community
- **Production Scale**: 6-20 People
- **Development Mode**: CLASSIC
- **Architectural Rationale**: A statically linked Go binary that embeds its React UI and supports SQLite, MySQL or PostgreSQL keeps deployment to one container, while typed plugin interfaces extend auth, storage, search and AI without forking.
- **Live Website Reference**: https://answer.apache.org
- **Source Repository**: https://github.com/apache/answer
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Go, Gin, TypeScript, React, Bootstrap, MySQL, PostgreSQL, SQLite, Docker, Kubernetes
- **Primary Language(s)**: Go, TypeScript
- **License of the reference repo**: Apache-2.0
- **Frontend**: React — Single-page admin and community UI under `ui/`, routed with `react-router-dom`, state in Zustand and SWR for data.; TypeScript — The whole `ui/` package is TypeScript with an Airbnb-style ESLint setup.; Bootstrap — UI kit via `react-bootstrap`, `bootstrap` and `bootstrap-icons`; styles in SCSS.; Create React App — Built with `react-scripts` customised through `react-app-rewired`/`customize-cra` (`ui/config-overrides.js`).; CodeMirror — Markdown editor for questions and answers (`@codemirror/lang-markdown`), rendered with `marked`.; i18next — Frontend translations backed by the `i18n/` YAML catalogue synced through Crowdin.
- **Backend & APIs**: Go — Single binary (`cmd/answer`) on Go 1.25; layered `internal/` packages for controller, service, repo, entity, router and migrations.; Gin — HTTP framework (`gin-gonic/gin`) with Brotli compression and `go-playground/validator` for request validation.; Google Wire — Compile-time dependency injection; the graph is declared in `cmd/wire.go` and generated into `cmd/wire_gen.go`.; Swagger — API docs generated by `swag` into `docs/swagger.json` and `docs/swagger.yaml` during `make generate`.; Model Context Protocol — `mark3labs/mcp-go` lets the server expose an MCP interface; `go-openai` backs AI features and `plugin/agent.go` defines agent plugins.
- **Data & persistence**: MySQL — Supported database via `go-sql-driver/mysql`.; PostgreSQL — Supported database via `lib/pq`.; SQLite — Default zero-dependency database; the Docker image is built with the `sqlite sqlite_unlock_notify` tags and ships the `sqlite` CLI.
- **Infrastructure & deploy**: Docker — Two-stage image: `golang:1.25-alpine` builds the binary and UI, a plain `alpine` image runs it with a `/data` volume on port 80.; Kubernetes — Helm chart under `charts/` for cluster installs.; GoReleaser — Cross-platform release binaries (`.goreleaser.yaml`, `build-binary-for-release.yml`).
- **Tooling, testing & ops**: GitHub Actions — Lint, ASF license-header check and image/binary builds for releases and tests; a GitLab CI file also exists.; golangci-lint — Go linting pinned in the Makefile (v2); `mockgen` generates test doubles.; pnpm — Frontend package manager (`pnpm@9.7.0`, Node >= 20) installed inside the Docker build to compile the UI.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/apache/answer @ 3b9f137)
1. **One static Go binary that embeds the React UI**: The Makefile builds `cmd/answer` with `CGO_ENABLED=0` and static linking, and the Dockerfile adds the `bindata` tag so the compiled `ui/build` is embedded through `ui/static.go`. Deploying Answer means shipping a single executable plus a `/data` directory.
2. **Bring your own database: SQLite, MySQL or PostgreSQL**: Drivers for all three are in `go.mod`, and the default image is compiled with SQLite tags so a trial needs no external service. The `internal/migrations` package keeps schema changes database-agnostic.
3. **Extension through a typed Go plugin system**: The `plugin/` package defines interfaces for cache, captcha, CDN, connectors (OAuth), embeds, filters, importers, KV storage, notifications, parsers, render, reviewer, search, sidebar, storage, user center and vector search. `script/build_plugin.sh` compiles the plugins listed in `script/plugin_list` into the binary at image build time.
4. **Compile-time wiring with Google Wire and a layered internal/ tree**: Instead of a runtime DI container, `cmd/wire.go` declares providers for `internal/controller`, `service`, `repo` and friends and `wire` generates the constructor graph, which keeps startup explicit and testable.
5. **AI and MCP built into the core rather than bolted on**: `go.mod` pulls `sashabaranov/go-openai` and `mark3labs/mcp-go`, and the plugin package includes `agent.go` and `vector_search.go`, so assistants and semantic search are first-class extension points.
6. **Governed as an Apache Software Foundation project**: `.asf.yaml`, the `check-asf-header.yml` workflow and `licenserc.toml` enforce ASF conventions; the license is Apache-2.0 and the Go module path is `github.com/apache/answer`.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (MySQL, PostgreSQL, SQLite): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.