filiksyos/gitsimilar

Purpose and Entry Points

GitSimilar is a Next.js application that finds GitHub repositories with similar declared integrations. It derives similarity from a target repository’s root env-template variables, uses Azure OpenAI to select stack-defining keys, then queries GitHub code search.

Primary UI routes are app/page.tsx and app/[owner]/[repo]/page.tsx. The server boundary is app/api/find-similar/route.ts.

Request and UI Flow

The home experience in app/page.tsx and components/SimilarHome.tsx accepts a GitHub repository identifier or URL. Repository-specific URLs are handled by app/[owner]/[repo]/page.tsx, which can initialize the same similarity workflow for a resolved owner/repo.

Client code calls the internal API rather than directly accessing GitHub or Azure credentials. Global application shell and styling live in app/layout.tsx and app/globals.css.

Similarity Orchestrator

app/api/find-similar/route.ts is the primary orchestration stage. It validates/parses the source repository, obtains its env template, extracts variable names, asks the model to choose 3–5 reusable keys, executes GitHub searches, and returns ranked repository results.

Core types exchanged between stages are centralized in lib/types.ts. Operational logging is isolated in lib/logger.ts, including optional AI-query output controlled by environment configuration.

GitHub Repository Inspection

lib/github.ts owns GitHub API interactions and forms the external-service boundary. The flow fetches repository metadata to resolve its default branch, reads the root tree, chooses the first supported env-template filename, then fetches its contents.

Repository input normalization is handled by lib/parse-repo.ts. Candidate env filenames and search constraints are represented by lib/search-limits.ts. GitHub authentication uses GITHUB_TOKEN; authenticated code search is effectively required and also improves rate-limit behavior.

Environment Template Extraction

lib/env-extractor.ts converts the discovered .env.example-style file into variable names. It supports active assignments, exported assignments, and commented template declarations, allowing repositories that document all integrations as comments to participate.

The source-template selection and GitHub content retrieval are separate from extraction: retrieval is in lib/github.ts, while parsing is in lib/env-extractor.ts. This keeps malformed or unsupported file content from leaking into search logic.

AI Key Selection

lib/azure-openai.ts invokes Azure OpenAI chat completions once per lookup. Prompt construction and the system instruction are defined in lib/prompts.ts and lib/prompts/system.md.

The model receives only extracted env-key names and must return ordered JSON keys: stack-defining/reusable integrations first, generic keys last. Azure configuration comes from AZURE_OPENAI_API_KEY, AZURE_OPENAI_BASE_URL, and optionally AZURE_OPENAI_MODEL.

Search, Retry, and Ranking

lib/web-search-agent.ts constructs GitHub /search/code queries using selected keys and the exact matched env filename, excluding forks. If no results are found, it removes the least-specific final key and retries up to twice.

Results are deduplicated by repository, exclude the source repository, and are sorted by popularity after GitHub metadata/GraphQL refresh. The response is capped at 100 candidates. Example repositories for the UI are maintained in lib/home-example-repos.ts.