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 <noreply@anthropic.com>
This commit is contained in:
Algis Dumbris
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
5248593e67
commit
fcb8da613c
@@ -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
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user