# filiksyos/gitsimilar architecture

> Architecture diagram of the GitHub repository filiksyos/gitsimilar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filiksyos/gitsimilar
- Repository: https://github.com/filiksyos/gitsimilar

## Overview

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

Main entry points: [`app/api/find-similar/route.ts`](https://github.com/filiksyos/gitsimilar/blob/master/app/api/find-similar/route.ts) (Find-similar orchestrator), [`lib/azure-openai.ts`](https://github.com/filiksyos/gitsimilar/blob/master/lib/azure-openai.ts) (AI key selector), [`lib/github.ts`](https://github.com/filiksyos/gitsimilar/blob/master/lib/github.ts) (GitHub inspection), [`lib/web-search-agent.ts`](https://github.com/filiksyos/gitsimilar/blob/master/lib/web-search-agent.ts) (Search and ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_home_route["Home route<br/>Next.js page<br/>[page.tsx]"]
  node_repo_route["Repository route<br/>Next.js page<br/>[page.tsx]"]
  node_similar_home["Similarity form<br/>client UI<br/>[SimilarHome.tsx]"]
  node_app_shell["App shell and styles<br/>layout<br/>[layout.tsx]"]
end

subgraph group_api["Similarity API"]
  node_api_route{{"Find-similar orchestrator<br/>API route<br/>[route.ts]"}}
  node_repo_parser["Repository parser<br/>input normalization<br/>[parse-repo.ts]"]
  node_github_client["GitHub inspection<br/>GitHub gateway<br/>[github.ts]"]
  node_env_extractor["Env-key extractor<br/>template parser<br/>[env-extractor.ts]"]
  node_ai_selector["AI key selector<br/>Azure OpenAI gateway<br/>[azure-openai.ts]"]
  node_prompts["Selection prompts<br/>prompt definition<br/>[prompts.ts]"]
  node_system_prompt["AI system instruction<br/>prompt document<br/>[system.md]"]
  node_search_agent["Search and ranking<br/>search agent"]
  node_shared_types["Shared contracts<br/>types<br/>[types.ts]"]
  node_logger["Operational logging<br/>[logger.ts]"]
  node_results["Ranked similar repositories<br/>API response"]
end

subgraph group_services["External Services"]
  node_github_api{{"GitHub API<br/>external API"}}
  node_azure_openai{{"Azure OpenAI<br/>external API"}}
end

node_app_shell -->|"wraps"| node_home_route
node_home_route -->|"renders"| node_similar_home
node_repo_route -->|"initializes"| node_similar_home
node_similar_home -->|"lookup request"| node_api_route
node_api_route -->|"validates input"| node_repo_parser
node_api_route -->|"inspects source repo"| node_github_client
node_github_client -->|"metadata, tree, contents"| node_github_api
node_github_client -->|"env template content"| node_env_extractor
node_env_extractor -->|"variable names"| node_ai_selector
node_prompts -->|"builds request"| node_ai_selector
node_system_prompt -->|"system instruction"| node_prompts
node_ai_selector -->|"chat completion"| node_azure_openai
node_ai_selector -->|"selected keys"| node_search_agent
node_search_agent -->|"code search and refresh"| node_github_api
node_search_agent -->|"ranked candidates"| node_results
node_api_route -->|"returns"| node_results
node_api_route -.->|"uses"| node_shared_types
node_api_route -.->|"logs lookup"| node_logger

click node_home_route "https://github.com/filiksyos/gitsimilar/blob/master/app/page.tsx"
click node_repo_route "https://github.com/filiksyos/gitsimilar/blob/master/app/%5Bowner%5D/%5Brepo%5D/page.tsx"
click node_similar_home "https://github.com/filiksyos/gitsimilar/blob/master/components/SimilarHome.tsx"
click node_app_shell "https://github.com/filiksyos/gitsimilar/blob/master/app/layout.tsx"
click node_api_route "https://github.com/filiksyos/gitsimilar/blob/master/app/api/find-similar/route.ts"
click node_repo_parser "https://github.com/filiksyos/gitsimilar/blob/master/lib/parse-repo.ts"
click node_github_client "https://github.com/filiksyos/gitsimilar/blob/master/lib/github.ts"
click node_env_extractor "https://github.com/filiksyos/gitsimilar/blob/master/lib/env-extractor.ts"
click node_ai_selector "https://github.com/filiksyos/gitsimilar/blob/master/lib/azure-openai.ts"
click node_prompts "https://github.com/filiksyos/gitsimilar/blob/master/lib/prompts.ts"
click node_system_prompt "https://github.com/filiksyos/gitsimilar/blob/master/lib/prompts/system.md"
click node_search_agent "https://github.com/filiksyos/gitsimilar/blob/master/lib/web-search-agent.ts"
click node_shared_types "https://github.com/filiksyos/gitsimilar/blob/master/lib/types.ts"
click node_logger "https://github.com/filiksyos/gitsimilar/blob/master/lib/logger.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home_route,node_repo_route,node_similar_home,node_app_shell toneBlue
class node_api_route,node_repo_parser,node_github_client,node_env_extractor,node_ai_selector,node_prompts,node_system_prompt,node_search_agent,node_shared_types,node_logger,node_results toneAmber
class node_github_api,node_azure_openai toneMint
```

## Components

### Next.js UI

- [Home route](https://github.com/filiksyos/gitsimilar/blob/master/app/page.tsx): Next.js page · `app/page.tsx`
- [Repository route](https://github.com/filiksyos/gitsimilar/blob/master/app/%5Bowner%5D/%5Brepo%5D/page.tsx): Next.js page · Initializes lookup from owner and repository URL parameters. · `app/[owner]/[repo]/page.tsx`
- [Similarity form](https://github.com/filiksyos/gitsimilar/blob/master/components/SimilarHome.tsx): client UI · Accepts a GitHub repository identifier or URL. · `components/SimilarHome.tsx`
- [App shell and styles](https://github.com/filiksyos/gitsimilar/blob/master/app/layout.tsx): layout · `app/layout.tsx`

### Similarity API

- [Find-similar orchestrator](https://github.com/filiksyos/gitsimilar/blob/master/app/api/find-similar/route.ts): API route · Coordinates validation, inspection, AI selection, search, and ranking. · `app/api/find-similar/route.ts`
- [Repository parser](https://github.com/filiksyos/gitsimilar/blob/master/lib/parse-repo.ts): input normalization · `lib/parse-repo.ts`
- [GitHub inspection](https://github.com/filiksyos/gitsimilar/blob/master/lib/github.ts): GitHub gateway · Resolves branches, locates root env templates, fetches content, and refreshes repository metadata. · `lib/github.ts`
- [Env-key extractor](https://github.com/filiksyos/gitsimilar/blob/master/lib/env-extractor.ts): template parser · Extracts active, exported, and commented template declarations. · `lib/env-extractor.ts`
- [AI key selector](https://github.com/filiksyos/gitsimilar/blob/master/lib/azure-openai.ts): Azure OpenAI gateway · Selects ordered reusable, stack-defining environment keys. · `lib/azure-openai.ts`
- [Selection prompts](https://github.com/filiksyos/gitsimilar/blob/master/lib/prompts.ts): prompt definition · `lib/prompts.ts`
- [AI system instruction](https://github.com/filiksyos/gitsimilar/blob/master/lib/prompts/system.md): prompt document · `lib/prompts/system.md`
- [Search and ranking](https://github.com/filiksyos/gitsimilar/blob/master/lib/web-search-agent.ts): search agent · Retries with fewer keys, deduplicates candidates, excludes source, and ranks by popularity. · `lib/web-search-agent.ts`
- [Shared contracts](https://github.com/filiksyos/gitsimilar/blob/master/lib/types.ts): types · Core data exchanged across lookup stages. · `lib/types.ts`
- [Operational logging](https://github.com/filiksyos/gitsimilar/blob/master/lib/logger.ts): logging · Optionally records AI-query output. · `lib/logger.ts`
- **Ranked similar repositories**: API response · Up to 100 candidate repositories.

### External Services

- **GitHub API**: external API · Repository contents, code search, and metadata/GraphQL access.
- **Azure OpenAI**: external API · Chat completion for key selection.

## Connections

- App shell and styles → Home route: wraps
- Home route → Similarity form: renders
- Repository route → Similarity form: initializes
- Similarity form → Find-similar orchestrator: lookup request
- Find-similar orchestrator → Repository parser: validates input
- Find-similar orchestrator → GitHub inspection: inspects source repo
- GitHub inspection → GitHub API: metadata, tree, contents
- GitHub inspection → Env-key extractor: env template content
- Env-key extractor → AI key selector: variable names
- Selection prompts → AI key selector: builds request
- AI system instruction → Selection prompts: system instruction
- AI key selector → Azure OpenAI: chat completion
- AI key selector → Search and ranking: selected keys
- Search and ranking → GitHub API: code search and refresh
- Search and ranking → Ranked similar repositories: ranked candidates
- Find-similar orchestrator → Ranked similar repositories: returns
- Find-similar orchestrator → Shared contracts: uses
- Find-similar orchestrator → Operational logging: logs lookup