Architecture

Shoehorn is built as a set of focused Go microservices communicating over gRPC, fronted by a REST API gateway and a Svelte single-page application.

System Overview

Service Descriptions

Service	Port (HTTP/gRPC)	Purpose
API	8080 / -	REST API gateway. Routes requests to microservices via gRPC. Handles authentication, authorization, tenant context, and search (via Meilisearch).
EventBus	8083 / 9083	Manages event streams via Redpanda (Kafka-compatible). Publishes and consumes domain events.
Worker	8085 / 9085	Background job processor. Handles async tasks like manifest processing, scorecard evaluation, and data enrichment.
Crawler	8086 / 9086	Repository discovery and GitHub integration. Fetches manifests, READMEs, and repository metadata.
Forge	8087 / 9087	Workflow engine and scaffolding. Manages molds (templates), workflow execution, and approval flows.

Data Flow

Authentication Flow

Kubernetes Data Flow

Entity Discovery Flow

Infrastructure Components

PostgreSQL 18

Primary data store with Row-Level Security (RLS) for multi-tenant isolation.

• RLS enforced: All tenant-scoped tables have RLS policies (always enabled)
• 2-user model: shoehorn_user (migrations, BYPASSRLS), app_user (runtime, NOBYPASSRLS)
• pgaudit: SQL audit logging enabled in production

Meilisearch

Full-text search engine providing sub-50ms fuzzy search.

• Indexes: entities, teams, documentation
• Supports typo-tolerance, faceted filtering, and ranking rules

Valkey

Redis-compatible in-memory cache.

• Entity and repository data caching
• Session data (when not using JWT)
• Rate limiting counters

Redpanda

Kafka-compatible event streaming platform.

• Domain events (entity created, updated, deleted)
• Webhook delivery
• Async job queuing

Cerbos

Policy-as-code authorization engine.

• RBAC policies defined in YAML
• Evaluates permissions per request
• Supports resource-level and action-level policies

Deployment Architecture