Build Decisions
What this guide is
This is an execution guide for shipping a data-connected chat feature with MooseStack and a Next.js reference client. It helps you make the key upfront decisions, get to a working baseline quickly (via the tutorial), then iterate toward production quality by improving context, adding sources, and embedding chat into your app experience (not leaving it as a demo UI).
What this guide is not
- A generic chatbot or a support bot, or RAG recipe, or guide to fine-tuning your chat or creating agents for common user questions.
- A one-size-fits-all architecture. This is a set of patterns you adapt to your constraints.
- A promise that "LLM answers are correct by default." You will design for verification, observability, and guardrails.
Implementation decisions
The decisions below define the shape of your chat system. The template defaults to a simple, opinionated stack (internal-first deployment, ClickHouse with rich metadata, SQL-backed tools via MCP, Claude Haiku as the model) and shows where to extend or harden as requirements grow.
| Decision | Options | Implementation |
|---|---|---|
| Data access scope | Narrow (specific tables) vs Broad (full schema) | Template uses readonly mode with row limits in mcp.ts; extend with table allowlists |
| Data sources | Batch (S3/Parquet), Operational (streams, OLTP replicas) | Tutorial covers S3/Parquet bulk load; see Ingest docs for streaming |
| Latency optimization | Raw tables, Materialized views, Denormalized models | Define MVs in moosestack-service/app/ for time buckets, top-N, common group-bys |
| Schema context | None, Table comments, Column comments with semantics | get_data_catalog tool exposes column comments; add JSDoc comments to your data models (see Appendix) |
| MCP tools | query_clickhouse only, Add catalog discovery, Add search/RAG | Both tools in moosestack-service/app/apis/mcp.ts; extend serverFactory() to add search or other tools |
| Model provider | Anthropic Claude, OpenRouter, Others | Set ANTHROPIC_API_KEY; change model in agent-config.ts; see example apps for OpenRouter integration |
| Deployment scope | Internal only, Customer-facing | Ship internal with audit trail; add governance before customer-facing |
| Authentication | No auth, API key, User JWT passthrough | Template uses PBKDF2 API key auth in mcp.ts; upgrade to JWT for user-scoped access |
| Access controls | Tool allowlists, Scoped views, Row-level security | Template enforces ClickHouse readonly mode; add scoped views for tenants; plan RLS for enterprise |