shortlink-org/shortlink

This system is a distributed microservices platform for managing and redirecting short links, featuring a modular architecture with distinct boundaries for API gateways, backend-for-frontend, and link management. It provides core functionality for link creation, metadata enrichment, and screenshot generation, while supporting multiple access protocols including HTTP, GraphQL, and gRPC. The infrastructure is heavily containerized with Kubernetes and Helm charts, and includes experimental proofs-of-concept for load testing, machine learning, and distributed transactions.

20 changes.

This period focused on establishing the foundational infrastructure and developer tooling for the project. Key activities included configuring the monorepo structure, setting up Ansible and Terraform for infrastructure as code, and creating modular build systems for local and remote environments. Additionally, proofs of concept for load testing, fuzzing, and CI/CD automation were introduced to support future development.

29 changes.

This period focused on establishing the foundational architecture for a new microservices ecosystem, introducing dedicated boundaries for the API gateway, proxy, metadata, and link services. Significant effort was directed toward containerization via comprehensive Dockerfiles and Kubernetes deployment configurations using Helm charts. The work also included implementing core business logic, such as link management and metadata extraction, alongside robust testing and observability integrations.

Introduces a proof-of-concept implementation for validating JSON Web Tokens using the Common Expression Language (CEL). The change adds Go code to compile and evaluate CEL rules (specifically for audience and expiration checks) and exposes an HTTP POST endpoint at /evaluate that accepts JWT claims and returns validation results. The implementation includes the core engine, routing, rule loading, and example CEL scripts.

poc/cel · high confidence

The link\_cqrs package introduces a new CQRS-based implementation for link use cases. It provides query methods (Get, List) that retrieve link data from a CQRS store, and event handlers that synchronize the CQRS store with domain events (LinkCreated, LinkUpdated, LinkDeleted, MetadataExtracted) by subscribing to message queues (Watermill) and updating the store accordingly.

_boundaries/link/internal/usecases/link\cqrs · high confidence

The 'boundaries/chrome-extension' directory was added, containing a README describing the ShortLink Chrome extension's features (parsing webpages for links, saving them for future reference), a .gitignore file, a main CSS file, and a logo SVG. This establishes the structural foundation for the Chrome extension component within the boundaries layer.

boundaries/link · high confidence

Introduces a new Gatling-based load testing setup for the poc/gatling module. This includes Scala test simulations (Debug, MaxPerformance, Stability) that execute a CommonScenario against the main page, along with configuration files (gatling.conf, simulation.conf, logback.xml) and a README. The framework supports console, file, and Graylog logging, as well as metrics export to Graphite/InfluxDB.

poc/gatling · high confidence

Added a new ML project structure under poc/ml-diff, including a GitLab CI pipeline configuration (ml-diff.yml) that triggers on tags, a Python training script (train.py) that fits a Random Forest classifier and outputs accuracy and confusion matrix, a Makefile with targets for dependency management, testing, and linting, a .gitignore for generated artifacts, and a README.

poc/ml-diff · high confidence

The API boundary now includes a complete Nginx configuration to handle HTTP traffic, including a main nginx.conf for performance and logging, a default.conf template with security headers and static file handling, and an ssl.conf template for SSL/TLS settings. This establishes the web server configuration for the API service.

ops/dockerfile/boundaries/api · high confidence

Users can now spin up a local Kubernetes cluster using Vagrant, VirtualBox, and Ansible. The new configuration files define a multi-VM environment (defaulting to 4 instances) with specific memory, CPU, and network settings, and include a Makefile target to provision the cluster using a specific Kubernetes version (v1.14.0).

poc/vagrant · medium confidence

Added a new proof-of-concept in the poc/xa directory that demonstrates a distributed transaction using the X/Open XA pattern. This includes a Go-based example application that integrates with the DTM (Distributed Transaction Manager) to manage a saga-style transaction across two microservice endpoints (TransIn and TransOut) with corresponding compensation logic. The change also provides a Docker Compose setup to run the necessary PostgreSQL and DTM services locally, along with a README explaining the advantages and disadvantages of the XA pattern compared to alternatives like SAGA and TCC.

poc/xa · high confidence

A new shell script, cleanup\_pods.sh, has been added to the ops/script directory. This script automates the deletion of pods in specific non-running states (Evicted, Error, CrashLoopBackOff, and ContainerStatusUnknown) across all namespaces. A corresponding README.md has also been added to document the script's purpose and usage.

ops/script · high confidence

The 'ui-next' Ansible role has been added to automate the deployment of the new UI. This includes provisioning a Docker container for the 'shortlink-org/shortlink-ui-next' image, configuring Nginx as a reverse proxy, and setting up scheduled cron jobs to fetch settlement reports and handle retries.

ops/ansible/playbooks/roles/ui-next · high confidence

The \ops/terraform\ directory now contains the foundational Terraform configuration files (\main.tf\, \variables.tf\, \versions.tf\) and a \.gitignore\ for local state and lock files. This setup defines providers for PostgreSQL and Kubernetes, declares sensitive variables for database credentials, and enforces a minimum Terraform version of 1.14.8.

ops/terraform · high confidence

The metadata boundary now includes a new parsers package that implements the application logic for extracting metadata (description, keywords, image URL) from a given URL. The implementation fetches the HTML content, parses it using goquery, and stores the result in the metadata store. This change introduces the core logic for the 'Parse metadata from URL' feature, including the use case struct, the Get and Set operations, and corresponding unit tests.

boundaries/metadata/internal/usecases/parsers · high confidence

The nginx role has been added to the Ansible playbook, introducing a new configuration for the gateway servers. This includes a custom nginx.conf, TLS certificate and key files, and tasks to install nginx, copy configuration files, and manage TLS certificates. The role also includes a Molecule test suite for automated testing.

ops/ansible/playbooks/roles/nginx · high confidence

The metadata boundary now includes a new screenshot use-case that captures a headless browser rendering of a given URL and stores the resulting image in S3-compatible storage (Minio). Users can trigger screenshot generation for a URL, after which the system navigates to the page, waits for content to load, captures the screenshot, and saves it to the media repository.

boundaries/metadata/internal/usecases/screenshot · high confidence

New Dockerfiles and configuration files are introduced for the support boundary: a support-proxy image based on NGINX 1.29-alpine-otel serving static content and proxying PHP requests, and a support image based on PHP 8.5-fpm-alpine with Opcache, status endpoint, and Pyroscope integration. These files define how the support service is built and run, including health checks, user permissions, and PHP extensions.

ops/dockerfile/boundaries/platform/support · high confidence

Added ClusterFuzzLite configuration files (Dockerfile, build script, and project manifest) to enable automated fuzz testing for the Go codebase. The setup clones the shortlink repository, installs the go-fuzz-build tool, and configures the project to use libFuzzer on x86\_64 architectures, specifically targeting the FuzzBatch function in the pkg/batch package.

.clusterfuzzlite · high confidence

Introduced new AI assistant configuration files to guide code generation and development practices. The \.cursorrules\ file establishes Git workflow policies, such as requiring explicit user confirmation before pushing changes, and enforces English-only commit messages. Additionally, the \go-microservices.mdc\ file provides comprehensive guidelines for Go microservices development, covering Clean Architecture, error handling, security, observability with OpenTelemetry, and testing standards.

.cursor · high confidence

A new Dockerfile and associated configuration have been added to build the shortdb service. The build process utilizes Go 1.26 with several experimental features enabled, including the json/v2 package, and targets the Debian 13.4 base image. The resulting container includes health checks and exposes the service on port 9090.

ops/dockerfile/boundaries/shortdb · high confidence

A new Node.js utility has been added to the common script boundaries. This script fetches a secret from a Kubernetes cluster and writes the value to a .env file. It accepts command-line arguments for the namespace, secret name, key, and environment variable key, allowing users to easily retrieve and store Kubernetes secrets locally.

boundaries/common/script · high confidence

The repository now includes the \geerlingguy.docker\ and \geerlingguy.pip\ Ansible roles, each with full support for automated testing and continuous integration. The Docker role installs Docker and Docker Compose on Linux systems, while the Pip role installs Python's package manager and manages Python packages. Both roles include GitHub Actions workflows for linting and Molecule-based integration testing, along with standard metadata, licensing, and configuration files.

ops/ansible/playbooks/roles/geerlingguy.docker · high confidence

Users can now use new shell scripts in the poc/scripts directory to automate environment setup. The k8s\_create\_cluster\_on\_gcloud.sh script provisions a Google Kubernetes Engine cluster with specific configurations, while install-protobuf.sh installs Protocol Buffers on Linux or macOS. A README.md file was also added to document these scripts.

poc/scripts · high confidence

The BFF (Backend for Frontend) service is introduced with a new project structure, including a Go entry point, Makefile for build and test automation, and comprehensive documentation. This includes Architecture Decision Records (ADRs) detailing the use of oapi-codegen and the C4 system model, alongside environment variable configurations and Postman collections for API testing.

boundaries/bff · high confidence

The link boundary now provides full CRUD operations (Add, Get, List, Update, Delete) for managing links. Each operation is implemented as a saga to ensure consistency, such as saving to the store, managing permissions via Authzed, and publishing domain events. The Get use case enforces access control by checking if a link is public or, for private links, verifying the user's email against an allowlist via the Kratos Admin API. The List use case retrieves links based on user permissions, and the Add/Update/Delete operations publish corresponding events to the CQRS event bus.

boundaries/link/internal/usecases/link · high confidence

The mobile application for ShortLink has been initialized with a complete development environment. This includes an Expo-based app structure configured for iOS and Android, along with end-to-end testing via Detox. The setup provides scripts to run the app locally, build for different environments, and execute automated tests on simulators and emulators.

(repo-wide) · high confidence

The proxy service is now packaged as a Helm chart (version 0.3.2) that depends on the shortlink-template chart (v0.12.6). The chart configures the proxy to use HTTPRoute-based routing with a No-Vary-Search header, enables Kafka support via environment variables, and sets up health checks and monitoring. This change provides a standardized way to deploy and manage the proxy service within the Kubernetes cluster.

boundaries/proxy/ops/proxy · high confidence

Added new files to the \poc/danger/danger\ directory to support commit message validation and CI-specific logic. The \commit\_linter.rb\ file introduces a \CommitLinter\ class that enforces rules on commit subjects and bodies, such as length limits, capitalization, and the absence of emojis or short references. The \emoji\_checker.rb\ file provides the underlying logic to detect text and Unicode emojis in commit messages. Additionally, \gitlab\_danger.rb\ defines rules for distinguishing between local and CI-only execution, while \helper.rb\ and \request\_helper.rb\ provide utility methods for file categorization, HTML linking, and HTTP requests. These changes enable automated feedback on commit message quality within the GitLab CI environment.

poc/danger/danger · medium confidence

A new Helm chart named 'common' (version 0.2.3) has been added to provide general Kubernetes manifests, specifically a PriorityClass for ArgoCD, and a configurable Redis deployment. The chart bundles the 'shortlink-template' (v0.12.6) and 'redis' (v25.3.11) dependencies, with Redis enabled by default and configured with specific resource limits, persistence settings, and Prometheus monitoring integrations.

boundaries/common/ops/common · high confidence

Added new Dockerfiles and corresponding .dockerignore files for the shop-admin, shop-bff, and shop-ui boundaries. The admin boundary now uses a Python 3.14-slim base image with uv for dependency management. The bff boundary is built on Node.js 24.15.0-alpine, and the ui boundary also uses Node.js 24.15.0-alpine with Next.js 15.0.0-rc.0. Each Dockerfile includes specific environment variables, health checks, and user permissions tailored to each service.

ops/dockerfile/boundaries/shop · high confidence

The metadata service is now initialized with a complete project structure, including a Makefile for build and documentation tasks, a buf.yaml for gRPC/Protobuf configuration, and a Go entry point (cmd/main.go) that initializes the service using the go-sdk. Additionally, the directory now contains architectural decision records (ADRs) and a README that describes the service's role in enriching link information and generating screenshots.

boundaries/metadata · high confidence

Added Dockerfiles and .dockerignore files for the marketing referral service and the notification bot service. The referral service is a Python application exposing ports 8000 and 9090, while the bot service is a Java application built with Maven and exposing port 9090. Both include health checks and use tini as the entrypoint.

ops/dockerfile/boundaries/marketing · high confidence

The repository now includes dedicated Dockerfiles and associated .dockerignore files for several platform components, each defining how they are built and run. The Backstage service is containerized using Node.js 24.15.0, while the CSI component is built with Go 1.26-alpine and runs on Alpine Linux 3.23. A new Go-based WebAssembly (WASM) build is provided for the Istio extension. Additionally, the Landscape service is containerized using the public.ecr.aws/g6m3a0y9/landscape2 image and served via NGINX 1.29-alpine-otel. These files establish the build and runtime environments for these specific platform boundaries.

ops/dockerfile/boundaries/platform · high confidence

The build system has been refactored by splitting the monolithic Makefile into modular components. New make targets are now available for managing Ansible playbooks, generating TLS certificates via cfssl, building and documenting the CLI tool, configuring Docker and Git, running Go tests and linters, generating Protocol Buffers with Buf, managing Terraform state, and controlling Vagrant VMs. This structure improves maintainability and allows developers to run specific operational tasks without triggering the entire build suite.

ops/Makefile · high confidence

The UI boundary is now initialized with essential configuration and environment files. This includes environment templates for development, Kubernetes, and production (\.env.dev\, \.env.k8s\, \.env.prod\) containing placeholders for API, Sentry, and Firebase settings. The directory also introduces a \.cursor\ rule file to guide frontend development using React, NextJS, and TailwindCSS, alongside standard tooling configurations like \.dockerignore\, \.gitignore\, \.npmrc\, and \.prettierrc\ to standardize the build and development environment.

boundaries/ui · high confidence

The \ops/docker-compose\ directory now contains complete, new docker-compose definitions for every application service, including the API gateway, auth services (Keycloak, Kratos, Hydra, Keto, SpiceDB), link service, logger, metadata service, support proxy, and the Next.js UI. Each service is configured with its own network, dependencies, build context, and environment variables, establishing a standardized local development environment.

ops/docker-compose · high confidence

The proxy service is introduced with a full project scaffold, including a TypeScript/ESM configuration (tsconfig.json), ESLint rules enforcing Clean Architecture boundaries, and a Vitest setup for integration testing with Testcontainers. The service exposes an OpenAPI specification for redirecting short links and implements a Zero-Trust security model using a permissions.json file that restricts file system, environment, and network access (including Kafka and gRPC endpoints). Additionally, Makefiles and proto generation tasks are added to support the service's build and code generation workflows.

boundaries/proxy · high confidence

The repository has been initialized with essential configuration files and documentation to support development and contribution. This includes a \.code-workspace\ file that defines the monorepo structure, mapping bounded contexts like the API Gateway, BFF, Link Service, and UI to their respective paths. A comprehensive \.env.example\ file is added, providing environment variable templates for configuring stores (Postgres, MongoDB, Redis, etc.), logging, tracing, and API settings. Additionally, a \.golangci.yml\ file configures the Go linter with strict rules for code quality, and other files like \Makefile\, \README.md\, and \AGENTS.md\ establish the project's operational and architectural guidelines.

(repo-wide) · high confidence

Added the SBT build configuration for the Gatling proof-of-concept, including the \build.properties\ file pinning SBT version 1.12.9, the \plugins.sbt\ file adding the \gatling-sbt\ plugin version 4.18.1, and a \Dependencies.scala\ file defining project dependencies such as \gatling-charts-highcharts\, \gatling-test-framework\, \logback-gelf\, \gatling-picatinny\, and \janino\.

poc/gatling/project · high confidence

The API Gateway service now includes a comprehensive README and Architecture Decision Records (ADRs) that outline the system's support for HTTP REST, GraphQL, gRPC, and WebSocket protocols. The documentation details the architectural split of the gateway into separate services for each protocol, providing context on the design choices and consequences for client integration.

boundaries/api/api-gateway · high confidence

The metadata service now instruments its use cases with OpenTelemetry tracing, creating spans for parser and screenshot operations within the saga workflow. This adds observability into the metadata flow, allowing users to track the progress and status of metadata and screenshot generation steps, including handling of non-critical errors like unavailable screenshots.

boundaries/metadata/internal/usecases/metadata · high confidence

The system now enforces merge request standards through a new Danger-based review process. Merge requests are validated for title capitalization, description presence, and commit message formatting. The system also automatically suggests assignees and reviewers, enforces required labels, and inherits labels from closed issues. Additionally, it automatically assigns milestones based on related issues and ensures proper metadata is applied to each merge request.

poc/danger, poc/systemd · high confidence

The Nginx configuration template for the Next.js UI has been updated to enable QUIC and HTTP/3 support. This change adds the 'quic' and 'http2' directives to the server block, allowing the UI to serve content over the newer HTTP/3 protocol alongside standard SSL/TLS connections.

ops/ansible/playbooks/templates · high confidence

A new certificate and private key pair for GitLab container registry authentication have been added to the repository. This enables secure, certificate-based authentication for the GitLab registry, ensuring that registry access is properly secured and verified.

ops/cert/gitlab · medium confidence

The Kubernetes operational commands have been reorganized into a modular structure under ops/Makefile/k8s/. This introduces separate Makefiles for managing Minikube, Helm, Skaffold, Telepresence, and Velero, each providing specific commands to control local development environments, deploy charts, and handle backups. A new common configuration enables kubectl applyset pruning, and a custom Helm README template improves documentation generation.

ops/Makefile/k8s · high confidence

The proxy service's dependency injection has been refactored to use the Awilix library with a CLASSIC injection mode to prevent issues with controller instantiation. The container now explicitly registers controllers, infrastructure, domain, and application components, with special handling for components requiring explicit injection (e.g., ProxyController, message bus, event publisher). This change improves the reliability of the proxy service's internal wiring and resolves previous DI container issues.

boundaries/proxy/src/di · medium confidence

The proxy application layer now enforces a consistent error-handling strategy and a reusable execution pipeline. A new exception hierarchy (ApplicationError, ValidationError, InfrastructureError) and a centralized ErrorHandler provide structured, typed errors with appropriate HTTP status codes and logging. A UseCasePipeline with interceptors (Logging, Metrics, Authorization) wraps use-case execution, ensuring cross-cutting concerns like telemetry and access control are applied uniformly. DTOs (GetLinkRequest/Response) and use cases (GetLinkByHash, PublishEvent) are decoupled from transport layers, and the LinkApplicationService orchestrates redirects through this pipeline.

boundaries/proxy/src/infrastructure · high confidence

Added end-to-end and integration tests for the proxy boundary; Added unit tests for EventDispatcher and LinkRedirectedEventHandler; Added unit tests for GetLinkByHash and PublishEvent use cases.

A new go.mod file has been added for the api-gateway boundary, establishing the module as github.com/shortlink-org/shortlink/boundaries/api/api-gateway. The module targets Go 1.26.2 and declares a comprehensive set of direct and indirect dependencies, including gRPC, OpenTelemetry, and the internal go-sdk packages, effectively defining the build and dependency graph for this component.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 28 → 45 (+16.6)
• Rubric changed (rubric-2026.08.18 → rubric-2026.08.19) — scores are not directly comparable.

• Code Health 81 (new)
• Architecture 75 (new)
• Maturity 13 → 81 (+67.5)
• Readiness 15 → 28 (+12.8)
• Security 100 → 49 (-51.5)
• Domain Modelling 90 (new)
• Event-Driven 100 (new)
• Accessibility 51 (new)

• No automated tests
• No tests found
• bus factor not measured — no commits were sampled
• early-stage repository — too little history to judge knowledge freshness
• single-commit history — no usable git history window to measure hotspots

• Consequences are restatements rather than trade-offs (e.g. learning curve for PlantUML/C4-PlantUML vs existing tools) (docs/ADR/decisions/0011-application-architecture-documentation.md)
• Consequences are thin ('We use next material for made our logger format') rather than trade-offs such as OTel integration cost or operational complexity (docs/ADR/decisions/0010-logger-format.md)
• Consequences are thin: only one bullet stating the outcome and no trade-offs (e.g. performance cost of reduced transparency) (docs/ADR/decisions/0039-ui-accessibility.md)
• Consequences section is sparse and only lists benefits with no trade-offs (e.g. vendor lock-in to Storybook tools, component quality vs. third-party alternatives) (docs/ADR/decisions/0040-ui-kit.md)
• Context and consequences are both cited to an external source (Michael Nygard's blog + adr-tools repo), leaving the ADR itself uninformative and its own rationale buried in links (docs/ADR/decisions/0001-record-architecture-decisions.md)
• Context and decision are identical ('We want to have a monorepository...') with no context/problem and no consequences; only one sentence in body (docs/ADR/decisions/0012-use-monorepository.md)
• Context is 'We want to know product metrics by each services.' and Decision is 'We made grafana dashboard for product-metrics by each services.' with Consequences only beginning ('1. Requirements dashboard') (docs/ADR/decisions/0008-product-metrics-by-services.md)
• Context is a one-line rationale ('We use tracing and logging systems to track application events') with no trade-offs; consequences are citations rather than real consequences (docs/ADR/decisions/0009-naming-spans-and-attributes.md)
• Context is a single sentence ('We want to use integration tests to verify the correctness of our code.') and decision restates 'We will use k6' with no rationale; consequences are boilerplate install commands (go install + xk6 build) plus one plugin link (docs/ADR/decisions/0020-k6.md)
• Context is thin ("This ADR addresses the need to standardize our code style tool, considering efficiency and developer experience."), decision is a one-line rationale with no trade-offs or alternatives considered (docs/ADR/decisions/0032-python-code-style-selection.md)
• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (boundaries/mobile/pnpm-lock.yaml)
• Critical CVE: [GHSA redacted] (boundaries/api/api-gateway/go.mod)
• Critical CVE: [GHSA redacted] (boundaries/bff/go.mod)
• Critical CVE: [GHSA redacted] (boundaries/link/go.mod)
• Critical CVE: [GHSA redacted] (boundaries/mobile/pnpm-lock.yaml)
• Critical CVE: [GHSA redacted] (boundaries/bff/go.mod)
• Critical CVE: [GHSA redacted] (boundaries/ui/pnpm-lock.yaml)
• Critical CVE: [GHSA redacted] (boundaries/chrome-extension/pnpm-lock.yaml)
• Critical CVE: [GHSA redacted] (boundaries/mobile/pnpm-lock.yaml)
• …and 139 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

shortlink-org/shortlink was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.