# himanshuksr0007/why-code architecture

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

- Interactive diagram: https://gitdiagram.com/himanshuksr0007/why-code
- Repository: https://github.com/himanshuksr0007/why-code

## Overview

Why-Code turns repository history and source structure into a Neo4j evidence graph, then answers questions with cited evidence or refuses unsupported claims. The principal workflow runs from repository selection and ingestion through decision/structure extraction and graph indexing to retrieval, validation, and answer presentation. The product also includes decision auditing, graph exploration, sharing, accounts, and custom model settings. Edges are limited to relationships explicit in the excerpts or README; several implementation details are unsampled, so those links are omitted.

Main entry points: [`backend/app/retrieval/api/routes.py`](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/api/routes.py) (Ask and evidence routes), [`backend/app/retrieval/service.py`](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/service.py) (Retrieval pipeline), [`backend/app/graph/neo4j_driver.py`](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/graph/neo4j_driver.py) (Evidence graph), [`backend/app/ingestion/service.py`](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/ingestion/service.py) (History ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Repository indexing"]
  node_ingestion["History ingestion<br/>[service.py]"]
  node_intent["Decision extraction<br/>[pipeline.py]"]
  node_structure["Code structure extraction<br/>[pipeline.py]"]
  node_graph[("Evidence graph<br/>[neo4j_driver.py]")]
end

subgraph group_answer["Grounded answers"]
  node_api["API application<br/>[main.py]"]
  node_retrieval_api["Ask and evidence routes<br/>[routes.py]"]
  node_retrieval["Retrieval pipeline<br/>[service.py]"]
  node_live["Live repository service<br/>[live_service.py]"]
  node_llm["LLM provider<br/>[provider.py]"]
  node_models["Model management<br/>[service.py]"]
end

subgraph group_explore["Decision exploration"]
  node_decision_ui["Decision center"]
  node_graph_ui["Graph explorer<br/>[graph-explorer.tsx]"]
  node_records_api["Decision records API<br/>[routes.py]"]
end

subgraph group_accounts["Accounts and sharing"]
  node_auth["Authentication<br/>[service.py]"]
  node_shares["Chat sharing<br/>[service.py]"]
end

subgraph group_client["Web experience"]
  node_web["Why-Code app<br/>[page.tsx]"]
  node_answer_ui["Answer presentation<br/>[answer-panel.tsx]"]
  node_ask_ui["Question workspace<br/>[ask-workspace.tsx]"]
  node_share_ui["Share viewer<br/>[share-viewer.tsx]"]
  node_settings_ui["Settings<br/>[settings-page.tsx]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_web
node_web -.->|"asks via"| node_retrieval_api
node_retrieval_api -->|"invokes"| node_retrieval
node_retrieval_api -->|"asks live service"| node_live
node_retrieval -->|"synthesizes with"| node_llm
node_retrieval -.->|"retrieves evidence"| node_graph
node_retrieval_api -.->|"returns cited answer"| node_answer_ui
node_ask_ui -.->|"submits question"| node_retrieval_api
node_ingestion -.->|"supplies history"| node_intent
node_ingestion -.->|"supplies repository"| node_structure
node_intent -.->|"records decisions"| node_graph
node_structure -.->|"writes structure"| node_graph
node_visitor -->|"browses decisions"| node_decision_ui
node_decision_ui -.->|"loads audit records"| node_records_api
node_visitor -->|"explores connections"| node_graph_ui
node_visitor -->|"manages models"| node_settings_ui
node_settings_ui -.->|"configures model"| node_models
node_visitor -->|"creates account"| node_auth
node_visitor -->|"views shared chat"| node_share_ui
node_share_ui -.->|"loads share"| node_shares
node_api -->|"mounts routes"| node_retrieval_api
node_api -->|"mounts routes"| node_records_api

click node_web "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/app/page.tsx"
click node_api "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/main.py"
click node_ingestion "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/ingestion/service.py"
click node_intent "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/intent/pipeline.py"
click node_structure "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/structural/pipeline.py"
click node_graph "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/graph/neo4j_driver.py"
click node_retrieval_api "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/api/routes.py"
click node_retrieval "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/service.py"
click node_live "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/live_service.py"
click node_llm "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/intent/llm/provider.py"
click node_answer_ui "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/answer/answer-panel.tsx"
click node_ask_ui "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/ask/ask-workspace.tsx"
click node_decision_ui "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/decisions/decision-explorer.tsx"
click node_graph_ui "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/graph/graph-explorer.tsx"
click node_records_api "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/features/routes.py"
click node_models "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/models/service.py"
click node_auth "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/auth/service.py"
click node_shares "https://github.com/himanshuksr0007/why-code/blob/main/backend/app/shares/service.py"
click node_share_ui "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/share/share-viewer.tsx"
click node_settings_ui "https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/settings/settings-page.tsx"

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_ingestion,node_intent,node_structure,node_graph toneBlue
class node_api,node_retrieval_api,node_retrieval,node_live,node_llm,node_models toneAmber
class node_decision_ui,node_graph_ui,node_records_api toneMint
class node_auth,node_shares toneRose
class node_web,node_answer_ui,node_ask_ui,node_share_ui,node_settings_ui,node_visitor toneIndigo
```

## Components

### Repository indexing

- [History ingestion](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/ingestion/service.py): `backend/app/ingestion/service.py`
- [Decision extraction](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/intent/pipeline.py): `backend/app/intent/pipeline.py`
- [Code structure extraction](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/structural/pipeline.py): `backend/app/structural/pipeline.py`
- [Evidence graph](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/graph/neo4j_driver.py): `backend/app/graph/neo4j_driver.py`

### Grounded answers

- [API application](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/main.py): `backend/app/main.py`
- [Ask and evidence routes](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/api/routes.py): `backend/app/retrieval/api/routes.py`
- [Retrieval pipeline](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/service.py): `backend/app/retrieval/service.py`
- [Live repository service](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/retrieval/live_service.py): `backend/app/retrieval/live_service.py`
- [LLM provider](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/intent/llm/provider.py): `backend/app/intent/llm/provider.py`
- [Model management](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/models/service.py): `backend/app/models/service.py`

### Decision exploration

- [Decision center](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/decisions/decision-explorer.tsx): `frontend/src/components/decisions/decision-explorer.tsx`
- [Graph explorer](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/graph/graph-explorer.tsx): `frontend/src/components/graph/graph-explorer.tsx`
- [Decision records API](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/features/routes.py): `backend/app/features/routes.py`

### Accounts and sharing

- [Authentication](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/auth/service.py): `backend/app/auth/service.py`
- [Chat sharing](https://github.com/himanshuksr0007/why-code/blob/main/backend/app/shares/service.py): `backend/app/shares/service.py`

### Web experience

- [Why-Code app](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Answer presentation](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/answer/answer-panel.tsx): `frontend/src/components/answer/answer-panel.tsx`
- [Question workspace](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/ask/ask-workspace.tsx): `frontend/src/components/ask/ask-workspace.tsx`
- [Share viewer](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/share/share-viewer.tsx): `frontend/src/components/share/share-viewer.tsx`
- [Settings](https://github.com/himanshuksr0007/why-code/blob/main/frontend/src/components/settings/settings-page.tsx): `frontend/src/components/settings/settings-page.tsx`

### Other components

- **Visitor**

## Connections

- Visitor → Why-Code app: opens
- Why-Code app → Ask and evidence routes: asks via
- Ask and evidence routes → Retrieval pipeline: invokes (evidence: `backend/app/retrieval/api/routes.py`)
- Ask and evidence routes → Live repository service: asks live service (evidence: `backend/app/retrieval/api/routes.py`)
- Retrieval pipeline → LLM provider: synthesizes with (evidence: `backend/app/retrieval/service.py`)
- Retrieval pipeline → Evidence graph: retrieves evidence
- Ask and evidence routes → Answer presentation: returns cited answer
- Question workspace → Ask and evidence routes: submits question
- History ingestion → Decision extraction: supplies history
- History ingestion → Code structure extraction: supplies repository
- Decision extraction → Evidence graph: records decisions
- Code structure extraction → Evidence graph: writes structure
- Visitor → Decision center: browses decisions
- Decision center → Decision records API: loads audit records
- Visitor → Graph explorer: explores connections
- Visitor → Settings: manages models
- Settings → Model management: configures model
- Visitor → Authentication: creates account
- Visitor → Share viewer: views shared chat
- Share viewer → Chat sharing: loads share
- API application → Ask and evidence routes: mounts routes (evidence: `backend/app/main.py`)
- API application → Decision records API: mounts routes (evidence: `backend/app/main.py`)
