How vibioh/ketchup works
Project Type & Purpose
• This is a full-stack Go application composed of three separate executables (cmd/ketchup, cmd/checker, cmd/notifier).
• It provides a simple HTML UI/API to let users sign up and view dependency checks, runs a background checker to poll external package registries, and sends digest emails via the notifier.
• It follows a layered/hexagonal style: entrypoints under cmd/, business logic under pkg/, storage under pkg/store, external integrations under pkg/provider, and SQL migrations under sql/.
Main Components
a. Frontend (User’s Browser)
• Renders HTML/CSS/JS served by cmd/ketchup
b. API & Web Service (cmd/ketchup)
• HTTP server with endpoints (/health, /ready, /version, signup, suggestion UI)
• Template rendering via pkg/ketchup/renderer
• Middleware (CSP, CORS, logging, OpenTelemetry) from pkg/middleware
c. Background Checker Service (cmd/checker)
• Scheduled job
• pkg/provider clients (GitHub, Docker, Helm, NPM, PyPI)
• pkg/ketchup logic writes “ketchup” records to Postgres & caches tokens/locks in Redis
d. Notifier Service (cmd/notifier)
• Reads pending “ketchups” from Postgres
• Uses pkg/notifier to format email digests
• Sends via external mailer API
e. Shared Storage
• Postgres (pkg/model, pkg/store) holds users, repositories, ketchups, signup info
• Redis for captcha tokens and distributed locks
f. External Services
• GitHub API, Docker registry, Helm chart repo, NPM, PyPI
• Mailer endpoint
• Datadog/OpenTelemetry collector
Relationships & Data Flow
• Browser → HTTP (cmd/ketchup) → Postgres/Redis → Browser
• Cron scheduler → Checker service → External Providers → Postgres/Redis
• Notifier service → Postgres → Mailer API → User Inbox
• All services emit telemetry to Datadog/Otel collector
Architectural Patterns & Principles
• Layered/hexagonal architecture: separation of cmd (adapters), pkg/provider (ports), pkg/service (use cases), pkg/store (driven adapters), pkg/model (domain).
• Repository pattern for DB access (pkg/store/repository).
• Dependency injection via constructor functions in cmd/*.
• 12-factor compliance (config via env/CLI, stateless services, logs to stdout).
• Graceful shutdown and health/ready probes for Kubernetes readiness.
Final Checklist
• Clear component labels and grouping.
• Notes on periodic jobs and probe endpoints.
• Version/migration step (SQL folder) can be noted but not deeply detailed.