# xuanyuanzhifeng/code-panorama architecture

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

- Interactive diagram: https://gitdiagram.com/xuanyuanzhifeng/code-panorama
- Repository: https://github.com/xuanyuanzhifeng/code-panorama

## Overview

1. **Overall shape**
   - This is a Next.js 15 + React 19 application, but most of the interactive product lives in `src/` while server-side integration lives in `app/api/`.
   - The app is a code-analysis workspace: the user selects a GitHub repo or local directory, the backend reads source files, the AI layer infers structure/call chains, and the client renders an interactive graph plus linked source/log views.

2. **Client UI boundary**
   - `src/App.tsx` is the main client-side shell, with `src/components/*` providing the graph canvas, custom nodes, repo/path inputs, and agent logs.
   - `src/hooks/useGithubAgent.ts` appears to orchestrate the analysis workflow from the UI side, coordinating requests, state updates, and progressive graph expansion.
   - `src/utils/layout.ts` likely handles graph layout before rendering in the viewer.

3. **Visualization subsystem**
   - `src/components/GraphViewer.tsx` is the center of the result view and likely uses React Flow / XYFlow for the call graph.
   - `CustomNode.tsx` controls how nodes are rendered and annotated.
   - `AgentLog.tsx` exposes the analysis trace to the user, which is important because the tool is agent-driven and iterative rather than a single-shot report.

4. **Input and source-selection flow**
   - The entry point is a repo/path input UI (`RepoInput.tsx`, `LocalPathInput.tsx`).
   - From there, the app branches into two source acquisition paths: GitHub-based analysis and local filesystem analysis.
   - The user experience is intentionally split because the trust boundary differs: GitHub can be fetched remotely, while local path analysis requires the server to access that filesystem directly.

5. **GitHub source subsystem**
   - `app/api/github/*` exposes repo validation, tree listing, content fetching, and search endpoints.
   - `lib/github.ts` contains the lower-level GitHub integration logic, including token-aware access for private repos.
   - The data flow is: client submits repo info → API validates → tree/search/content endpoints fetch source material → analysis logic consumes the retrieved files.

6. **Local filesystem subsystem**
   - `app/api/local/*` mirrors the GitHub API shape with tree, content, search, validate, and a picker endpoint.
   - `lib/localSource.ts` and `lib/localApiError.ts` encapsulate filesystem access and user-facing error handling.
   - This subsystem is server-bound: the backend reads paths on the machine where the app is running, so it only works when the server can see the target directory.

7. **LLM / analysis subsystem**
   - `app/api/llm/json/route.ts` is the AI gateway, used for structured responses rather than free-form text.
   - `lib/openaiCompat.ts` suggests the app talks to an OpenAI-compatible endpoint, not just OpenAI itself, which matches the README’s configurable base URL/model/API key.
   - `lib/aiCallLogger.ts` indicates that model calls are traced, which feeds the agent log and helps explain how the final graph was produced.

8. **Persistence and history**
   - `app/api/history/list`, `item`, and `save` expose a history store for prior analyses.
   - `lib/historyStore.ts` uses `better-sqlite3`, so history is persisted server-side in a lightweight embedded database rather than an external service.
   - This creates a clear separation: analysis state and source retrieval are transient, while saved runs are durable and reloadable.

9. **Settings and configuration**
   - `app/api/settings/llm-defaults` serves default model settings, likely derived from environment variables.
   - The README states that user-editable settings are stored in browser `localStorage`, so the app does not rely on a server profile or account model.
   - This means configuration is split: defaults come from the server/env, while user overrides are client-local.

10. **Application shell and runtime**
   - `app/layout.tsx`, `app/page.tsx`, and `app/ClientAppShell.tsx` form the Next.js page entry and client wrapper.
   - `server.ts` implies a Node-based custom server entry for self-hosted runs.
   - The repo also contains `src/main.tsx`, `index.html`, and `vite.config.ts`, which looks like legacy or alternative client build scaffolding; the architecture to diagram should center on the Next.js App Router paths unless you are explicitly modeling that alternate build path.

11. **Typical end-to-end flow**
   - User enters a GitHub URL or local path → frontend validates the source → backend enumerates tree/files and fetches content → LLM analyzes entry points and call chains → graph and log views update progressively → the run can be saved to history and later reopened.
   - The graph view and source view are tightly linked, so node selection likely drives file/content highlighting while logs explain why each node exists.

12. **Key architectural boundaries to draw**
   - Client UI vs server APIs.
   - Remote GitHub source vs local filesystem source.
   - Source acquisition vs LLM reasoning.
   - Ephemeral analysis session vs persisted history.
   - Browser-local settings vs server-side defaults and secrets.

Main entry points: [`src/App.tsx`](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/App.tsx) (Main app), [`src/components/GraphViewer.tsx`](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/GraphViewer.tsx) (Graph view), [`app/api/llm/json/route.ts`](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/api/llm/json/route.ts) (LLM API), [`src/hooks/useGithubAgent.ts`](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/hooks/useGithubAgent.ts) (Agent hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_app_shell["App shell<br/>Next.js entry<br/>[page.tsx]"]
  node_client_wrapper["Client wrap<br/>Next.js client<br/>[ClientAppShell.tsx]"]
  node_main_app["Main app<br/>React workspace<br/>[App.tsx]"]
  node_repo_input["Repo input<br/>source picker<br/>[RepoInput.tsx]"]
  node_local_input["Local input<br/>source picker<br/>[LocalPathInput.tsx]"]
  node_graph_viewer["Graph view<br/>graph renderer<br/>[GraphViewer.tsx]"]
  node_custom_node["Node render<br/>graph node UI<br/>[CustomNode.tsx]"]
  node_agent_log["Agent log<br/>trace panel<br/>[AgentLog.tsx]"]
  node_github_agent["Agent hook<br/>workflow hook<br/>[useGithubAgent.ts]"]
  node_layout_util["Layout<br/>[layout.ts]"]
end

subgraph group_server["Server APIs"]
  node_github_api["GitHub API<br/>route group"]
  node_local_api["Local API<br/>route group"]
  node_llm_api["LLM API<br/>route group<br/>[route.ts]"]
  node_history_api["History API<br/>route group"]
  node_settings_api["Defaults API<br/>route group<br/>[route.ts]"]
end

subgraph group_sources["Source Access"]
  node_github_lib["GitHub lib<br/>integration<br/>[github.ts]"]
  node_local_lib["Local source<br/>filesystem<br/>[localSource.ts]"]
end

subgraph group_analysis["Analysis"]
  node_ai_gateway["AI gateway<br/>model client<br/>[openaiCompat.ts]"]
  node_ai_logger["Call logger<br/>trace logger<br/>[aiCallLogger.ts]"]
end

subgraph group_storage["Storage"]
  node_history_store["History store<br/>sqlite store<br/>[historyStore.ts]"]
end

node_app_shell -->|"mounts"| node_client_wrapper
node_client_wrapper -->|"hosts"| node_main_app
node_main_app -->|"source UI"| node_repo_input
node_main_app -->|"source UI"| node_local_input
node_main_app -->|"renders"| node_graph_viewer
node_main_app -->|"shows"| node_agent_log
node_github_agent -->|"drives"| node_repo_input
node_github_agent -->|"updates"| node_graph_viewer
node_github_agent -->|"streams"| node_agent_log
node_graph_viewer -->|"uses"| node_custom_node
node_graph_viewer -->|"lays out"| node_layout_util
node_repo_input -->|"validates"| node_github_api
node_local_input -->|"validates"| node_local_api
node_github_api -->|"fetches"| node_github_lib
node_local_api -->|"reads"| node_local_lib
node_github_api -->|"feeds"| node_llm_api
node_local_api -->|"feeds"| node_llm_api
node_llm_api -->|"calls"| node_ai_gateway
node_llm_api -->|"traces"| node_ai_logger
node_history_api -->|"persists"| node_history_store
node_settings_api -->|"defaults"| node_main_app
node_main_app -->|"saves"| node_history_api

click node_app_shell "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/page.tsx"
click node_client_wrapper "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/ClientAppShell.tsx"
click node_main_app "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/App.tsx"
click node_repo_input "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/RepoInput.tsx"
click node_local_input "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/LocalPathInput.tsx"
click node_graph_viewer "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/GraphViewer.tsx"
click node_custom_node "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/CustomNode.tsx"
click node_agent_log "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/AgentLog.tsx"
click node_github_agent "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/hooks/useGithubAgent.ts"
click node_layout_util "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/utils/layout.ts"
click node_github_api "https://github.com/xuanyuanzhifeng/code-panorama/tree/main/app/api/github"
click node_local_api "https://github.com/xuanyuanzhifeng/code-panorama/tree/main/app/api/local"
click node_llm_api "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/api/llm/json/route.ts"
click node_history_api "https://github.com/xuanyuanzhifeng/code-panorama/tree/main/app/api/history"
click node_settings_api "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/api/settings/llm-defaults/route.ts"
click node_github_lib "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/github.ts"
click node_local_lib "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/localSource.ts"
click node_ai_gateway "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/openaiCompat.ts"
click node_ai_logger "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/aiCallLogger.ts"
click node_history_store "https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/historyStore.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_app_shell,node_client_wrapper,node_main_app,node_repo_input,node_local_input,node_graph_viewer,node_custom_node,node_agent_log,node_github_agent,node_layout_util toneBlue
class node_github_api,node_local_api,node_llm_api,node_history_api,node_settings_api toneAmber
class node_github_lib,node_local_lib toneMint
class node_ai_gateway,node_ai_logger toneRose
class node_history_store toneIndigo
```

## Components

### Client UI

Browser shell, inputs, graph viewer, and log rendering.

- [App shell](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/page.tsx): Next.js entry · Page and client wrapper that bootstraps the application. · `app/page.tsx`
- [Client wrap](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/ClientAppShell.tsx): Next.js client · Client-side shell around the interactive workspace. · `app/ClientAppShell.tsx`
- [Main app](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/App.tsx): React workspace · Primary browser application that coordinates the product UI. · `src/App.tsx`
- [Repo input](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/RepoInput.tsx): source picker · UI for GitHub repository selection and validation. · `src/components/RepoInput.tsx`
- [Local input](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/LocalPathInput.tsx): source picker · UI for choosing and validating local filesystem paths. · `src/components/LocalPathInput.tsx`
- [Graph view](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/GraphViewer.tsx): graph renderer · Interactive call/structure graph display. · `src/components/GraphViewer.tsx`
- [Node render](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/CustomNode.tsx): graph node UI · Custom node presentation and annotations inside the graph. · `src/components/CustomNode.tsx`
- [Agent log](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/components/AgentLog.tsx): trace panel · Visible analysis trace and explanation stream. · `src/components/AgentLog.tsx`
- [Agent hook](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/hooks/useGithubAgent.ts): workflow hook · Client workflow coordinator for progressive analysis and graph expansion. · `src/hooks/useGithubAgent.ts`
- [Layout](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/src/utils/layout.ts): graph layout · Prepares node positions before rendering. · `src/utils/layout.ts`

### Server APIs

Next.js route handlers and backend integration points.

- [GitHub API](https://github.com/xuanyuanzhifeng/code-panorama/tree/main/app/api/github): route group · Server endpoints for remote repository validation, tree, content, and search. · `app/api/github`
- [Local API](https://github.com/xuanyuanzhifeng/code-panorama/tree/main/app/api/local): route group · Server endpoints for local path validation, tree, content, search, and picking. · `app/api/local`
- [LLM API](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/api/llm/json/route.ts): route group · Structured model-call gateway. · `app/api/llm/json/route.ts`
- [History API](https://github.com/xuanyuanzhifeng/code-panorama/tree/main/app/api/history): route group · Endpoints for listing, retrieving, and saving past analyses. · `app/api/history`
- [Defaults API](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/app/api/settings/llm-defaults/route.ts): route group · Server-provided LLM defaults for the client settings layer. · `app/api/settings/llm-defaults/route.ts`

### Source Access

GitHub and local filesystem acquisition paths.

- [GitHub lib](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/github.ts): integration · Token-aware GitHub access and fetch helpers. · `lib/github.ts`
- [Local source](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/localSource.ts): filesystem · Filesystem access and local-source error handling. · `lib/localSource.ts`

### Analysis

LLM gateway, logging, and graph shaping.

- [AI gateway](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/openaiCompat.ts): model client · OpenAI-compatible model transport and response shaping. · `lib/openaiCompat.ts`
- [Call logger](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/aiCallLogger.ts): trace logger · Captures model-call traces for the agent log. · `lib/aiCallLogger.ts`

### Storage

Persisted history and configuration defaults.

- [History store](https://github.com/xuanyuanzhifeng/code-panorama/blob/main/lib/historyStore.ts): sqlite store · Embedded persistence for saved analysis runs. · `lib/historyStore.ts`

## Connections

- App shell → Client wrap: mounts · The page loads the client wrapper.
- Client wrap → Main app: hosts · The client wrapper hosts the interactive workspace.
- Main app → Repo input: source UI · Users can start with a GitHub repository.
- Main app → Local input: source UI · Users can also start with a local path.
- Main app → Graph view: renders · The main app renders the graph result view.
- Main app → Agent log: shows · The main app exposes the analysis trace panel.
- Agent hook → Repo input: drives · The agent workflow coordinates repo-based analysis.
- Agent hook → Graph view: updates · Progressive analysis expands and refreshes the graph.
- Agent hook → Agent log: streams · Analysis steps are reflected in the log.
- Graph view → Node render: uses · The viewer relies on custom node rendering.
- Graph view → Layout: lays out · Graph layout is prepared before rendering.
- Repo input → GitHub API: validates · Repository selection is validated through server APIs.
- Local input → Local API: validates · Local path selection is validated through server APIs.
- GitHub API → GitHub lib: fetches · Route handlers delegate to GitHub integration logic.
- Local API → Local source: reads · Route handlers delegate to local filesystem access.
- GitHub API → LLM API: feeds · Fetched repository data is sent for structured analysis.
- Local API → LLM API: feeds · Fetched local source data is sent for structured analysis.
- LLM API → AI gateway: calls · The API reaches an OpenAI-compatible model backend.
- LLM API → Call logger: traces · Model calls are recorded for explanation and debugging.
- History API → History store: persists · Saved runs are written to embedded SQLite storage.
- Defaults API → Main app: defaults · Client settings are seeded from server-provided defaults.
- Main app → History API: saves · The UI can store and reopen analysis history.
