From fcb8da613c43b29497d0b4d9fe8e0fbb3115dc1a Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Fri, 13 Mar 2026 20:13:58 +0200 Subject: [PATCH] docs: add implementation plan and research for production readiness Covers 5 workstreams: git hooks, CI/CD, observability, deployment artifacts, and website. All constitution gates pass. Co-Authored-By: Claude Opus 4.6 --- specs/001-production-readiness/plan.md | 137 +++++++++++++++++++++ specs/001-production-readiness/research.md | 49 ++++++++ 2 files changed, 186 insertions(+) create mode 100644 specs/001-production-readiness/plan.md create mode 100644 specs/001-production-readiness/research.md diff --git a/specs/001-production-readiness/plan.md b/specs/001-production-readiness/plan.md new file mode 100644 index 0000000..108aad2 --- /dev/null +++ b/specs/001-production-readiness/plan.md @@ -0,0 +1,137 @@ +# Implementation Plan: SynapBus Production Readiness & Website Launch + +**Branch**: `001-production-readiness` | **Date**: 2026-03-13 | **Spec**: [spec.md](spec.md) +**Input**: Feature specification from `/specs/001-production-readiness/spec.md` + +## Summary + +Transform SynapBus from MVP to production-ready by adding: (1) git pre-commit/pre-push hooks for quality gates, (2) GitHub Actions CI for PR validation and release builds, (3) Prometheus metrics and Kubernetes health endpoints, (4) Dockerfile + docker-compose + Helm chart, (5) public website at synapbus.dev with documentation and blog. + +## Technical Context + +**Language/Version**: Go 1.23+ (server), SvelteKit 2 / Svelte 5 + Tailwind (website) +**Primary Dependencies**: prometheus/client_golang, chi/v5, cobra, modernc.org/sqlite +**Storage**: SQLite (embedded, pure Go) — unchanged +**Testing**: `go test ./...` (CGO_ENABLED=0), Python E2E tests +**Target Platform**: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64 +**Project Type**: Multi-deliverable: Go service + deployment artifacts + static website +**Performance Goals**: Health endpoints <10ms, metrics scrape <100ms, website LCP <2s +**Constraints**: Zero CGO, single binary, all deps pure Go +**Scale/Scope**: 5 workstreams, ~25 files to create/modify + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +| Principle | Status | Notes | +|-----------|--------|-------| +| I. Single Binary | PASS | Prometheus is compiled into binary. Docker/Helm are deployment artifacts. | +| II. MCP-Native | PASS | No changes to MCP interface. | +| III. Pure Go, Zero CGO | PASS | prometheus/client_golang is pure Go. No CGO required. | +| IV. Multi-Tenant | PASS | No changes to tenant model. | +| V. Embedded OAuth | PASS | No changes to auth. | +| VI. Semantic Storage | PASS | No storage changes. | +| VII. Swarm Patterns | PASS | No changes to swarm. | +| VIII. Observable | PASS | Prometheus enhances observability. | +| IX. Progressive | PASS | Metrics are opt-in via --metrics flag. | +| X. Web UI | PASS | Website is separate; embedded UI unchanged. | + +All gates pass. No violations. + +## Project Structure + +### Documentation (this feature) + +```text +specs/001-production-readiness/ +├── plan.md # This file +├── research.md # Phase 0 output +├── spec.md # Feature specification +└── checklists/ + └── requirements.md # Validation checklist +``` + +### Source Code (repository root) + +```text +# Workstream 1: DevOps & Hooks +scripts/ +├── hooks/ +│ ├── pre-commit # go vet + golangci-lint + fast tests +│ └── pre-push # full tests + build verify + +# Workstream 2: CI/CD +.github/workflows/ +├── ci.yml # PR checks (lint, test, build) +└── release.yml # Tag-triggered release (binaries + Docker) + +# Workstream 3: Observability +internal/ +├── metrics/ +│ ├── metrics.go # Prometheus collector registration +│ ├── middleware.go # HTTP metrics middleware +│ └── metrics_test.go # Tests +└── health/ + ├── health.go # /healthz, /readyz handlers + └── health_test.go # Tests + +# Workstream 4: Deployment +Dockerfile # Multi-stage build +docker-compose.yml # Local dev stack +deploy/helm/synapbus/ +├── Chart.yaml +├── values.yaml +├── templates/ +│ ├── deployment.yaml +│ ├── service.yaml +│ ├── pvc.yaml +│ ├── ingress.yaml +│ ├── configmap.yaml +│ └── _helpers.tpl + +# Workstream 5: Website (separate repo) +~/repos/synapbus-website/ # SvelteKit on Cloudflare Pages +├── src/routes/ +│ ├── +page.svelte # Landing page +│ ├── docs/ # Documentation +│ ├── blog/ # Blog posts +│ └── install/ # Installation guide +├── static/ # Generated images +└── wrangler.toml # Cloudflare config +``` + +**Structure Decision**: Existing Go project structure is preserved. New packages added under `internal/` for metrics and health. Deployment artifacts at repo root. Website in separate repo. + +## Implementation Workstreams + +### WS-1: Git Hooks (P1, ~30 min) +- Create `scripts/hooks/pre-commit` and `scripts/hooks/pre-push` +- Add `make hooks` target to install them +- Test with intentional lint error + +### WS-2: CI/CD Workflows (P1, ~45 min) +- Create `.github/workflows/ci.yml` for PR checks +- Create `.github/workflows/release.yml` for tag releases +- Test by pushing branch + +### WS-3: Observability (P1, ~1 hour) +- Add `internal/metrics/` package with Prometheus collectors +- Add `internal/health/` package with /healthz and /readyz +- Wire into main.go router +- Add middleware for HTTP request metrics +- Write unit tests + +### WS-4: Deployment Artifacts (P2, ~1 hour) +- Create Dockerfile (multi-stage: builder + scratch) +- Create docker-compose.yml +- Create Helm chart in deploy/helm/synapbus/ +- Test Docker build locally + +### WS-5: Website (P2, ~2 hours) +- Create synapbus-website repo +- Scaffold SvelteKit + Tailwind project +- Build landing page with AI-generated hero images +- Create documentation pages +- Create 2 blog posts with diagrams +- Deploy to Cloudflare Pages +- Configure DNS for synapbus.dev diff --git a/specs/001-production-readiness/research.md b/specs/001-production-readiness/research.md new file mode 100644 index 0000000..2638ff9 --- /dev/null +++ b/specs/001-production-readiness/research.md @@ -0,0 +1,49 @@ +# Research: SynapBus Production Readiness + +## R1: Prometheus Client for Zero-CGO Go + +**Decision**: Use `github.com/prometheus/client_golang` v1.20+ +**Rationale**: Pure Go library, no CGO required. Industry standard for Go services. Provides promhttp handler, collectors, and middleware patterns. +**Alternatives considered**: VictoriaMetrics client (lighter but less ecosystem support), OpenTelemetry (heavier, would add complexity) + +## R2: Health Check Patterns + +**Decision**: Implement `/healthz` (liveness) and `/readyz` (readiness) following Kubernetes probe conventions. +**Rationale**: Standard K8s pattern. Liveness = "is the process alive" (always 200 unless deadlocked). Readiness = "can it serve traffic" (checks DB connectivity). +**Alternatives considered**: Single `/health` endpoint (already exists but doesn't distinguish liveness from readiness) + +## R3: Multi-Stage Docker Build + +**Decision**: Two-stage build: `golang:1.23-alpine` builder → `scratch` runtime with ca-certificates and tzdata. +**Rationale**: Scratch produces smallest possible image. CGO_ENABLED=0 ensures static binary. Alpine builder provides build tools without bloating runtime. +**Alternatives considered**: Alpine runtime (adds ~5MB but has shell for debugging), distroless (Google's option, slightly larger) + +## R4: Helm Chart Structure + +**Decision**: Standard Helm 3 chart with Deployment, Service, PVC, optional Ingress. Single values.yaml. +**Rationale**: Follows Helm best practices. PVC for data persistence. Ingress optional for cloud deployments. +**Alternatives considered**: Kustomize (less user-friendly), raw K8s manifests (no templating) + +## R5: GitHub Actions CI Strategy + +**Decision**: Two workflows: `ci.yml` (on PR) and `release.yml` (on tag push v*). Use `actions/setup-go@v5` and `actions/setup-node@v4`. +**Rationale**: Separating PR checks from releases keeps CI fast. Tag-based releases are idiomatic for Go projects. +**Alternatives considered**: GoReleaser (adds dependency), single workflow with conditionals (harder to maintain) + +## R6: Website Technology + +**Decision**: SvelteKit 2 + Svelte 5 + Tailwind in separate private repo, deployed to Cloudflare Pages. +**Rationale**: Matches user's tech preferences (see CLAUDE.md). Cloudflare Pages provides free hosting with edge CDN. Separate repo avoids bloating the Go project. +**Alternatives considered**: Astro (used for mcpproxy.app), Hugo (Go-native but less flexible for interactive pages) + +## R7: Pre-commit/Pre-push Hooks + +**Decision**: Shell scripts in `scripts/hooks/`, installed via `make hooks` symlink. +**Rationale**: Go projects don't use npm (no husky). Shell scripts are universal, zero dependencies. Graceful degradation if golangci-lint not installed. +**Alternatives considered**: lefthook (Go-based, good but adds dependency), pre-commit framework (Python dependency) + +## R8: Docker Image Registry + +**Decision**: ghcr.io/smart-mcp-proxy/synapbus +**Rationale**: GitHub Container Registry is free for public repos, integrates with GitHub Actions natively (GITHUB_TOKEN auth). +**Alternatives considered**: Docker Hub (rate limits), ECR (AWS-specific)