How xuanyuanzhifeng/code-panorama works
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: App.tsx Main app · GraphViewer.tsx Graph view · route.ts LLM API · useGithubAgent.ts Agent hook
Components 20
Client UI
Browser shell, inputs, graph viewer, and log rendering.
- App shell · Page and client wrapper that bootstraps the application.
app/page.tsx - Client wrap · Client-side shell around the interactive workspace.
app/ClientAppShell.tsx - Main app · Primary browser application that coordinates the product UI.
src/App.tsx - Repo input · UI for GitHub repository selection and validation.
src/components/RepoInput.tsx - Local input · UI for choosing and validating local filesystem paths.
src/components/LocalPathInput.tsx - Graph view · Interactive call/structure graph display.
src/components/GraphViewer.tsx - Node render · Custom node presentation and annotations inside the graph.
src/components/CustomNode.tsx - Agent log · Visible analysis trace and explanation stream.
src/components/AgentLog.tsx - Agent hook · Client workflow coordinator for progressive analysis and graph expansion.
src/hooks/useGithubAgent.ts - Layout · Prepares node positions before rendering.
src/utils/layout.ts
Server APIs
Next.js route handlers and backend integration points.
- GitHub API · Server endpoints for remote repository validation, tree, content, and search.
app/api/github - Local API · Server endpoints for local path validation, tree, content, search, and picking.
app/api/local - LLM API · Structured model-call gateway.
app/api/llm/json/route.ts - History API · Endpoints for listing, retrieving, and saving past analyses.
app/api/history - Defaults API · 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 · Token-aware GitHub access and fetch helpers.
lib/github.ts - Local source · Filesystem access and local-source error handling.
lib/localSource.ts
Analysis
LLM gateway, logging, and graph shaping.
- AI gateway · OpenAI-compatible model transport and response shaping.
lib/openaiCompat.ts - Call logger · Captures model-call traces for the agent log.
lib/aiCallLogger.ts
Storage
Persisted history and configuration defaults.
- History store · Embedded persistence for saved analysis runs.
lib/historyStore.ts
Connections 22
- 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.