# vibioh/ketchup architecture

> Architecture diagram of the GitHub repository vibioh/ketchup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vibioh/ketchup
- Repository: https://github.com/vibioh/ketchup

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["User's Browser"]:::external
        StaticAssets["Static Assets"]:::common
        Templates["Templates"]:::common
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        KetchupServer["ketchup HTTP Server (Go)"]:::service
        Middleware["HTTP Middleware"]:::common
        Renderer["Template Renderer"]:::common
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        Checker["Checker Service (cron)"]:::service
        NotifierSvc["Notifier Service"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["Postgres"]:::database
        Redis["Redis"]:::cache
        Migrations["SQL Migrations"]:::common
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GitHub["GitHub API"]:::external
        DockerReg["Docker Registry"]:::external
        HelmRepo["Helm Chart Repo"]:::external
        NPM["NPM Registry"]:::external
        PyPI["PyPI Registry"]:::external
        MailerAPI["Mailer API"]:::external
        Telemetry["Datadog/Otel Collector"]:::external
    end

    %% Relationships
    Browser -->|HTTP GET/POST| KetchupServer
    KetchupServer -->|serves static| StaticAssets
    KetchupServer -->|renders templates| Renderer
    KetchupServer -->|uses| Middleware
    KetchupServer -->|pgx/v4 over TCP| Postgres
    KetchupServer -->|Redis SET/GET| Redis
    KetchupServer -->|health/readiness| KetchupServer

    Checker -->|OAuth2 JSON API| GitHub
    Checker -->|registry API| DockerReg
    Checker -->|chart API| HelmRepo
    Checker -->|registry API| NPM
    Checker -->|registry API| PyPI
    Checker -->|writes results| Postgres
    Checker -->|caches tokens/locks| Redis

    NotifierSvc -->|reads pending| Postgres
    NotifierSvc -->|formats email| NotifierSvc
    NotifierSvc -->|sends via HTTP| MailerAPI

    Browser -.->|views updates| KetchupServer

    KetchupServer -->|export telemetry| Telemetry
    Checker -->|export telemetry| Telemetry
    NotifierSvc -->|export telemetry| Telemetry

    Migrations -->|defines schema| Postgres

    %% Click Events
    click StaticAssets "https://github.com/vibioh/ketchup/tree/main/cmd/ketchup/static/"
    click Templates "https://github.com/vibioh/ketchup/tree/main/cmd/ketchup/templates/"
    click KetchupServer "https://github.com/vibioh/ketchup/blob/main/cmd/ketchup/ketchup.go"
    click Middleware "https://github.com/vibioh/ketchup/blob/main/pkg/middleware/middleware.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/renderer.go"
    click Checker "https://github.com/vibioh/ketchup/blob/main/cmd/checker/checker.go"
    click NotifierSvc "https://github.com/vibioh/ketchup/blob/main/cmd/notifier/notifier.go"
    click Postgres "https://github.com/vibioh/ketchup/blob/main/pkg/store/user/user.go"
    click Postgres "https://github.com/vibioh/ketchup/blob/main/pkg/store/repository/repository.go"
    click Postgres "https://github.com/vibioh/ketchup/blob/main/pkg/store/repository/repository_version.go"
    click Postgres "https://github.com/vibioh/ketchup/blob/main/pkg/store/ketchup/ketchup.go"
    click Migrations "https://github.com/vibioh/ketchup/blob/main/sql/ddl.sql"
    click Migrations "https://github.com/vibioh/ketchup/blob/main/sql/migration_*.sql"
    click GitHub "https://github.com/vibioh/ketchup/blob/main/pkg/provider/github/github.go"
    click DockerReg "https://github.com/vibioh/ketchup/blob/main/pkg/provider/docker/docker.go"
    click HelmRepo "https://github.com/vibioh/ketchup/blob/main/pkg/provider/helm/helm.go"
    click NPM "https://github.com/vibioh/ketchup/blob/main/pkg/provider/npm/npm.go"
    click PyPI "https://github.com/vibioh/ketchup/blob/main/pkg/provider/pypi/pypi.go"
    click NotifierSvc "https://github.com/vibioh/ketchup/blob/main/cmd/notifier/config.go"
    click NotifierSvc "https://github.com/vibioh/ketchup/blob/main/cmd/notifier/clients.go"
    click NotifierSvc "https://github.com/vibioh/ketchup/blob/main/cmd/notifier/services.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/ketchup.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/signup.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/suggest.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/ketchups.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/cache.go"
    click Renderer "https://github.com/vibioh/ketchup/blob/main/pkg/ketchup/security.go"
    click NotifierSvc "https://github.com/vibioh/ketchup/blob/main/pkg/notifier/notifier.go"
    click NotifierSvc "https://github.com/vibioh/ketchup/blob/main/pkg/notifier/releases.go"
    click Postgres "https://github.com/vibioh/ketchup/tree/main/pkg/model/"
    click Migrations "https://github.com/vibioh/ketchup/blob/main/infra/web.yaml"
    click Migrations "https://github.com/vibioh/ketchup/blob/main/infra/notifier.yaml"

    %% Styles
    classDef service fill:#c6f5c6,stroke:#2d7a2d,color:#000
    classDef database fill:#c6d8ff,stroke:#2a3b8f,color:#000
    classDef cache fill:#ffe5b4,stroke:#b87700,color:#000
    classDef external fill:#eeeeee,stroke:#666666,color:#000
    classDef common fill:#f0f0f0,stroke:#888888,color:#000
```
