# kshitiz-shah/repowise architecture

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

- Interactive diagram: https://gitdiagram.com/kshitiz-shah/repowise
- Repository: https://github.com/kshitiz-shah/repowise

## Overview

RepoWise lets developers connect a public GitHub repository, index its source, explore a generated architecture graph, ask codebase questions with cited snippets, and analyze issues. The main path runs from the client through the authenticated Node API to repository/GitHub services and the independent FastAPI intelligence service. The graph also preserves account/session and the distinct indexing, architecture, retrieval, and issue-analysis capabilities. README and sampled files support the major routes and selected service wiring; unsampled AI route internals are shown at their enclosing service paths, with uncertain internal calls omitted.

Main entry points: [`ai-service/app/main.py`](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/main.py) (AI HTTP app), [`ai-service/app/services/retrieval_service.py`](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/retrieval_service.py) (RAG orchestration), [`ai-service/app/services/llm_service.py`](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/llm_service.py) (LLM service), [`client/src/App.tsx`](https://github.com/kshitiz-shah/repowise/blob/main/client/src/App.tsx) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_ui["Workspace UI<br/>[App.tsx]"]
  node_clientapi["API client<br/>[api.ts]"]
  node_archview["Architecture graph"]
  node_graphhook["Graph state/layout"]
end

subgraph group_api["Node API"]
  node_routes["API routing"]
  node_authroutes["Auth routing<br/>[auth.routes.ts]"]
  node_repoctrl["Repository handlers"]
  node_authctrl["Auth handlers<br/>[auth.controller.ts]"]
  node_reposvc["Repository rules"]
  node_authsvc["Authentication<br/>[auth.service.ts]"]
  node_aisvc["AI client<br/>[ai.service.ts]"]
end

subgraph group_ai["AI intelligence"]
  node_aiapp["AI HTTP app<br/>[main.py]"]
  node_indexsvc["Source indexing"]
  node_archsvc["Architecture analysis"]
  node_issue["Issue analysis<br/>[issue_service.py]"]
  node_rag["RAG orchestration"]
  node_embed["Embeddings"]
  node_llm["LLM service<br/>[llm_service.py]"]
  node_providers["LLM providers<br/>[base.py]"]
  node_vectors["Vector service<br/>[vector_service.py]"]
end

subgraph group_state["Data and integrations"]
  node_postgres[("PostgreSQL")]
  node_qdrant[("Qdrant")]
  node_github["GitHub"]
  node_gemini["Gemini"]
  node_groq["Groq"]
end

node_developer(("Developer"))

node_developer -->|"uses"| node_ui
node_ui -->|"requests"| node_clientapi
node_ui -->|"renders"| node_archview
node_archview -->|"manages graph"| node_graphhook
node_clientapi -->|"calls API"| node_routes
node_routes -->|"dispatches"| node_repoctrl
node_authroutes -->|"dispatches"| node_authctrl
node_repoctrl -->|"loads files"| node_reposvc
node_repoctrl -->|"requests analysis"| node_aisvc
node_authctrl -->|"authenticates"| node_authsvc
node_reposvc -->|"reads/writes"| node_postgres
node_reposvc -->|"fetches source"| node_github
node_authsvc -->|"stores sessions"| node_postgres
node_aisvc -->|"forwards requests"| node_aiapp
node_aiapp -->|"dispatches indexing"| node_indexsvc
node_aiapp -->|"dispatches architecture"| node_archsvc
node_aiapp -->|"dispatches queries"| node_rag
node_aiapp -->|"dispatches issue analysis"| node_issue
node_indexsvc -->|"embeds code"| node_embed
node_indexsvc -->|"indexes vectors"| node_vectors
node_rag -->|"embeds query"| node_embed
node_rag -->|"searches chunks"| node_vectors
node_rag -->|"generates answers"| node_llm
node_issue -->|"requests analysis"| node_llm
node_archsvc -->|"requests structured output"| node_llm
node_vectors -->|"reads/writes vectors"| node_qdrant
node_llm -->|"selects/falls back"| node_providers
node_providers -.->|"calls"| node_gemini
node_providers -.->|"calls"| node_groq

click node_ui "https://github.com/kshitiz-shah/repowise/blob/main/client/src/App.tsx"
click node_clientapi "https://github.com/kshitiz-shah/repowise/blob/main/client/src/api.ts"
click node_archview "https://github.com/kshitiz-shah/repowise/blob/main/client/src/ArchitectureGraph.tsx"
click node_graphhook "https://github.com/kshitiz-shah/repowise/blob/main/client/src/hooks/useArchitectureGraph.ts"
click node_routes "https://github.com/kshitiz-shah/repowise/blob/main/server/src/routes/repository.routes.ts"
click node_authroutes "https://github.com/kshitiz-shah/repowise/blob/main/server/src/routes/auth.routes.ts"
click node_repoctrl "https://github.com/kshitiz-shah/repowise/blob/main/server/src/controllers/repository.controller.ts"
click node_authctrl "https://github.com/kshitiz-shah/repowise/blob/main/server/src/controllers/auth.controller.ts"
click node_reposvc "https://github.com/kshitiz-shah/repowise/blob/main/server/src/services/repository.service.ts"
click node_authsvc "https://github.com/kshitiz-shah/repowise/blob/main/server/src/services/auth.service.ts"
click node_aisvc "https://github.com/kshitiz-shah/repowise/blob/main/server/src/services/ai.service.ts"
click node_aiapp "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/main.py"
click node_indexsvc "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/indexing_service.py"
click node_archsvc "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/architecture_service.py"
click node_issue "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/issue_service.py"
click node_rag "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/retrieval_service.py"
click node_embed "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/embedding_service.py"
click node_llm "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/llm_service.py"
click node_providers "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/providers/base.py"
click node_vectors "https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/vector_service.py"

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_ui,node_clientapi,node_archview,node_graphhook toneBlue
class node_routes,node_authroutes,node_repoctrl,node_authctrl,node_reposvc,node_authsvc,node_aisvc toneAmber
class node_aiapp,node_indexsvc,node_archsvc,node_issue,node_rag,node_embed,node_llm,node_providers,node_vectors toneMint
class node_postgres,node_qdrant,node_github,node_gemini,node_groq toneRose
class node_developer toneIndigo
```

## Components

### Client

- [Workspace UI](https://github.com/kshitiz-shah/repowise/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [API client](https://github.com/kshitiz-shah/repowise/blob/main/client/src/api.ts): `client/src/api.ts`
- [Architecture graph](https://github.com/kshitiz-shah/repowise/blob/main/client/src/ArchitectureGraph.tsx): `client/src/ArchitectureGraph.tsx`
- [Graph state/layout](https://github.com/kshitiz-shah/repowise/blob/main/client/src/hooks/useArchitectureGraph.ts): `client/src/hooks/useArchitectureGraph.ts`

### Node API

- [API routing](https://github.com/kshitiz-shah/repowise/blob/main/server/src/routes/repository.routes.ts): `server/src/routes/repository.routes.ts`
- [Auth routing](https://github.com/kshitiz-shah/repowise/blob/main/server/src/routes/auth.routes.ts): `server/src/routes/auth.routes.ts`
- [Repository handlers](https://github.com/kshitiz-shah/repowise/blob/main/server/src/controllers/repository.controller.ts): `server/src/controllers/repository.controller.ts`
- [Auth handlers](https://github.com/kshitiz-shah/repowise/blob/main/server/src/controllers/auth.controller.ts): `server/src/controllers/auth.controller.ts`
- [Repository rules](https://github.com/kshitiz-shah/repowise/blob/main/server/src/services/repository.service.ts): `server/src/services/repository.service.ts`
- [Authentication](https://github.com/kshitiz-shah/repowise/blob/main/server/src/services/auth.service.ts): `server/src/services/auth.service.ts`
- [AI client](https://github.com/kshitiz-shah/repowise/blob/main/server/src/services/ai.service.ts): `server/src/services/ai.service.ts`

### AI intelligence

- [AI HTTP app](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Source indexing](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/indexing_service.py): `ai-service/app/services/indexing_service.py`
- [Architecture analysis](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/architecture_service.py): `ai-service/app/services/architecture_service.py`
- [Issue analysis](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/issue_service.py): `ai-service/app/services/issue_service.py`
- [RAG orchestration](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/retrieval_service.py): `ai-service/app/services/retrieval_service.py`
- [Embeddings](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/embedding_service.py): `ai-service/app/services/embedding_service.py`
- [LLM service](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/llm_service.py): `ai-service/app/services/llm_service.py`
- [LLM providers](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/providers/base.py): `ai-service/app/providers/base.py`
- [Vector service](https://github.com/kshitiz-shah/repowise/blob/main/ai-service/app/services/vector_service.py): `ai-service/app/services/vector_service.py`

### Data and integrations

- **PostgreSQL**
- **Qdrant**
- **GitHub**
- **Gemini**
- **Groq**

### Other components

- **Developer**

## Connections

- Developer → Workspace UI: uses
- Workspace UI → API client: requests
- Workspace UI → Architecture graph: renders
- Architecture graph → Graph state/layout: manages graph
- API client → API routing: calls API
- API routing → Repository handlers: dispatches
- Auth routing → Auth handlers: dispatches
- Repository handlers → Repository rules: loads files
- Repository handlers → AI client: requests analysis
- Auth handlers → Authentication: authenticates
- Repository rules → PostgreSQL: reads/writes
- Repository rules → GitHub: fetches source
- Authentication → PostgreSQL: stores sessions
- AI client → AI HTTP app: forwards requests
- AI HTTP app → Source indexing: dispatches indexing
- AI HTTP app → Architecture analysis: dispatches architecture
- AI HTTP app → RAG orchestration: dispatches queries
- AI HTTP app → Issue analysis: dispatches issue analysis
- Source indexing → Embeddings: embeds code
- Source indexing → Vector service: indexes vectors
- RAG orchestration → Embeddings: embeds query
- RAG orchestration → Vector service: searches chunks
- RAG orchestration → LLM service: generates answers
- Issue analysis → LLM service: requests analysis
- Architecture analysis → LLM service: requests structured output
- Vector service → Qdrant: reads/writes vectors
- LLM service → LLM providers: selects/falls back
- LLM providers → Gemini: calls
- LLM providers → Groq: calls