Solution Block Hub

We build a lot of things at Aliz. Terraform modules, data pipelines, GenAI agents, app templates — hundreds of repositories across the organization. The problem is that nobody can find any of it. Someone on the Data track builds a BigQuery CDC pipeline, and six months later someone on AppDev builds the same thing from scratch because they didn't know the first one existed.

The Solution Block Hub fixes this. It's an AI-powered platform that automatically discovers, summarizes, and indexes our GitHub repositories — and puts a Gemini-based search assistant in front of the whole thing.

This page is the reference for what the Hub is, how it works, and how to make your work discoverable through it.

What's a Solution Block?

Before getting into the Hub itself, let's define the term. A Solution Block is a reusable, client-independent code artifact that solves a specific, repeatable problem. Think of it as something between a library and a project template — focused enough to be useful, generic enough to drop into any client engagement.

Solution Blocks follow strict rules:

• Naming: repository name starts with sb- (e.g., sb-composer, sb-data-pipeline)
• Tagging: the GitHub topic solution-block is applied
• Ownership: a CODEOWNERS file exists and the README identifies the responsible track (Data, Infra, AppDev, AI, or ML)
• Client independence: zero hardcoded client names, project IDs, or environment-specific values — everything is configurable
• Maturity label: explicitly stated as one of experimental, beta, production-ready, legacy, or deprecated

But the Hub doesn't stop at formal Solution Blocks. It also indexes templates, blueprints, GenAI agents, and any repository that looks like it could be reused — nearly 200 repositories as of mid-2026, and growing.

How It Works

The Hub is a fully automated pipeline built on GitHub Actions that runs on a schedule (Tuesdays and Thursdays). Here's the flow:

1. Discover

The repo-collector scans the entire aliz-ai GitHub organization and builds a list of candidate repositories. It pulls from multiple sources using OR logic — any repo matching any filter is included:

• GitHub topics (solution-block, value-proposition)
• Name patterns (sb-, genai, blueprint, agent, module, template)
• Description patterns
• Activity filters (created after a date, pushed recently, 800+ commits)

2. Filter

The repo-prefilter eliminates repos that don't need re-processing. It checks whether the summarization prompt version has changed and whether new commits exist since the last run. No point burning AI tokens on a repo that hasn't changed.

3. Summarize

The repo-summarizer is where the AI comes in. For each remaining repo, it clones the code and runs a carefully engineered prompt through GitHub Copilot CLI. The AI agent reads the repository — source code, configs, CI/CD pipelines, Terraform modules, tests — and produces a structured summary.

Each summary follows a strict template: purpose, maturity assessment, ideal use cases, negative triggers (when not to use it), key technologies, inputs/outputs, and notable design decisions. The prompt is versioned with semver, so we can track which prompt version generated which summary.

tip

The summarizer is smart about incremental updates. If a repo has an existing summary and only a few new commits landed, a cheaper model first decides whether the changes warrant re-summarization at all. If they do, the AI updates only the affected sections rather than regenerating everything.

4. Upload

The drive-uploader takes all generated summaries, wraps each in XML tags (<repo-summary github-repo-name="aliz-ai/repo-name">), and uploads the merged content to Google Docs via the Drive API. It also uploads the Gem's system prompt and knowledge base content from external sources like the Web Hub.

5. Serve

The final product is a Gemini Gem — a custom Gemini assistant available to everyone at Aliz. It reads the Google Docs as its knowledge base and acts as a Solution Block Advisor: you describe your project or problem in natural language, and the Gem searches through all indexed summaries to recommend relevant reusable assets.

Environment	What it's for
Production Gem	All Aliz employees — engineers, consultants, sales, project managers
Dev Gem	Developers working on the Hub itself

The Review Criteria

Not every repository is a Solution Block, and not every Solution Block is production-ready. The Hub includes a formal 10-section review framework that defines what "reusable" actually means:

1. Formal Requirements — naming, tagging, ownership, maturity
2. Focused Scope — solves one specific problem, not a project dump
3. Client Independence — no hardcoded client names, project IDs, or secrets
4. Structure & Portability — relative paths, modular Terraform, no hardcoded environments
5. Interface Predictability — documented inputs and outputs
6. Defensive Implementation — proper error handling, logging, no swallowed exceptions
7. Tech Stack & Dependencies — supported languages and frameworks, pinned versions
8. Documentation — concise and accurate (too verbose is almost as bad as absent)
9. Testing — core logic has tests, CI runs them
10. Security & Compliance — no secrets in code, scoped IAM roles, dependency scanning

Each criterion gets a verdict: Met, Partially Met, Not Met, or Skipped. The overall assessment lands on one of: Ready, Almost Ready, Needs Work, or Not a Candidate.

The Solution Block Hub repository also ships a Claude Code skill (solution-block-review) that lets you run this review directly from your terminal against any repository.

What This Means for You

If you maintain a reusable repository

Make it discoverable. At minimum:

1. Add the GitHub topic solution-block to your repo
2. Name it with the sb- prefix
3. Add a CODEOWNERS file
4. State the maturity level in your README
5. Document when to use it and when not to

The Hub's collector will pick it up on the next scheduled run, and the summarizer will generate a discovery-oriented summary automatically.

If you're starting a new project

Before writing code, ask the Gemini Gem: "What existing solution blocks could help with [your problem]?" You might find that half the work is already done.

If you want to contribute to the Hub itself

The Hub repository is a Python + Terraform project with a standard development workflow:

• repo-summarizer/ — Python (Poetry), handles discovery, filtering, and AI summarization
• drive-uploader/ — Python (Poetry), handles Google Docs publishing
• terraform/ — GCP infrastructure (Workload Identity Federation, service accounts)
• environments/ — per-environment config (dev, prod)

The pipeline is orchestrated entirely through GitHub Actions. Infrastructure changes go through Terraform plan/apply. The summarization prompt lives at repo-summarizer/prompts/summarize.prompt.md and follows semver — if you improve the prompt, bump the version and all repos get re-summarized on the next run.

note

The production collector config is deliberately broad. It goes beyond sb- repos to capture templates, GenAI projects, and high-activity repositories. If you think a repo should be included (or excluded), the filters live in environments/prod/collector-config.yaml.

Getting Help from the Aliz AI Framework

You don't have to work with the Hub by hand. The Aliz AI Framework ships a set of skills that plug directly into your coding assistant and effectively compare your codebase against the Solution Block Hub's data. Instead of manually querying the Gem, the skills can:

• Search on your behalf — analyze what you're building and surface the relevant solution blocks, templates, and agents already indexed by the Hub, so you reuse instead of rebuild.
• Help you contribute — check your repository against the Hub's expectations (naming, tagging, ownership, maturity, client independence) and guide you toward making it discoverable and review-ready.

If you already use the Aliz AI Framework, these skills are the fastest path into the Hub — both for finding existing work and for getting your own repositories onto the platform.

The Tech Stack

Component	Technology
Summarization engine	GitHub Copilot CLI (Claude Sonnet)
Prompt versioning	Semver in YAML frontmatter
Pipeline orchestration	GitHub Actions (5 chained workflows)
Infrastructure	Terraform on GCP (Workload Identity Federation)
Content publishing	Google Docs via Drive API
User-facing search	Gemini Gem
Application code	Python 3.12+, Poetry, Pydantic v2
Security	Dependabot, Trivy, Checkov, pre-commit hooks

Why This Matters

Consulting companies live and die by how fast they can deliver. Every hour spent rebuilding something that already exists is an hour not spent on the client's actual problem. The Solution Block Hub turns our collective repository history into a searchable, AI-indexed knowledge base — and it keeps itself up to date.

The pipeline runs twice a week. The summaries evolve with the code. The Gem is available to everyone, not just engineers who know which repo to look for.

If you've built something reusable, tag it. If you're starting something new, search first.