Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
import { lazy, Suspense, useCallback, useEffect, useMemo, useState } from 'react';
import type { JSX, ReactNode } from 'react';
import type { ArchitectureHotspot, ArchitectureOverviewDto } from '../core/intelligence-provider';
import {
ARCHITECTURE_VIEWS, readArchitectureConfig, saveArchitectureConfig,
} from './architecture-model';
import type { ArchitectureView, ConfigStorage } from './architecture-model';
import { architectureHistoryText as historyText, architectureText as text } from './strings';
import { peekNavigation, type NavigationHistory } from '../graph/navigation-history';
import { useDismissibleMenu } from '../graph/use-dismissible-menu';
import {
architectureEntryDetail, architectureEntryLabel, architectureEntryName, architectureHistoryOptions, initialArchitecturePlace,
type ArchitectureHistoryEntry, type PlaceChange, type RoutesPerspective, type SpatialPlace, type SystemPlace,
} from './architecture-history';
import { useArchitectureHistory } from './use-architecture-history';
import './architecture.css';
import { scenePaletteStyle } from './scene-palette';
import type { RepositoryMapProps } from './RepositoryMap';
import SpatialArchitecture from './SpatialArchitecture';
import RoutesArchitecture from './RoutesArchitecture';
import type { CoverageIndex } from '../app/tree-model';
import type { SystemArchitectureLoader } from './system-architecture-source';
import type { SelectionEvidenceListener } from '../galaxy/selection-evidence';
const SystemArchitecture = lazy(() => import('./SystemArchitecture'));
export interface ArchitecturePanelProps extends Pick<RepositoryMapProps, 'graph' | 'selection' | 'selectionPanel' | 'onSelect' | 'graphNote' | 'readSource'> {
projectName: string;
graphGeneration?: string;
active?: boolean;
/** Another surface (help, settings, a dialog) takes the keys: Alt+Left and Alt+Right stay with it. */
escapeTaken?: boolean;
coverage?: CoverageIndex;
overview?: ArchitectureOverviewDto;
loading?: boolean;
error?: string;
onRefresh?: () => void;
onClearSelection?: () => void;
onSelectionEvidence?: SelectionEvidenceListener;
systemArchitectureLoader?: SystemArchitectureLoader;
/** The declaration line is 1-based, as returned by the provider. */
onNavigate: (filePath: string, line?: number, name?: string) => void;
}
function browserStorage(): ConfigStorage | undefined {
try { return window.localStorage; } catch { return undefined; }
}
function Empty({ children }: { children?: ReactNode }): JSX.Element {
return <div className="atlas-arch-empty">{children ?? text.noData}</div>;
}
function SectionHeading({ title, note }: { title: string; note?: string }): JSX.Element {
return <div className="atlas-arch-section-heading"><div><h2>{title}</h2>{note && <p>{note}</p>}</div></div>;
}
/** Pagination bounds DOM work while keeping every returned finding reachable. */
function Collection<T>({ items, children, empty, pageSize = 12 }: {
items: T[]; children: (visible: T[]) => ReactNode; empty: string; pageSize?: number;
}): JSX.Element {
const [limit, setLimit] = useState(pageSize);
if (items.length === 0) return <Empty>{empty}</Empty>;
return <>
{children(items.slice(0, limit))}
{items.length > pageSize && <div className="atlas-arch-pager">
<span>{text.results(Math.min(limit, items.length), items.length)}</span>
{limit < items.length && <button className="atlas-arch-action" onClick={() => setLimit(limit + pageSize)}>{text.showMore}</button>}
</div>}
</>;
}
function SourceLink({ path, line, name, onNavigate }: {
path?: string; line?: number; name?: string; onNavigate: ArchitecturePanelProps['onNavigate'];
}): JSX.Element {
if (!path) return <span className="atlas-arch-muted" title={text.sourceMissing}>{text.unknown}</span>;
return <button className="atlas-arch-source" aria-label={text.openSource(name ?? path)}
onClick={() => onNavigate(path, line, name)}>{path}{line !== undefined ? `:${line}` : ''}</button>;
}
function HotspotSignals({ hotspot }: { hotspot: ArchitectureHotspot }): JSX.Element {
const signals = [hotspot.allocationInLoop && text.allocationInLoop,
hotspot.scanInLoop && text.scanInLoop, hotspot.unguardedRecursion && text.unguardedRecursion].filter(Boolean);
return <div className="atlas-arch-signals">{signals.map(signal => <span key={String(signal)} className="atlas-arch-badge">{signal}</span>)}</div>;
}
function Findings({ view, data, empty, onNavigate }: {
view: ArchitectureView; data: ArchitectureOverviewDto; empty: string; onNavigate: ArchitecturePanelProps['onNavigate'];
}): JSX.Element {
if (view === 'entryPoints') return <section><SectionHeading title={text.views.entryPoints} note={text.entryNote} />
<Collection items={data.entryPoints} empty={empty} pageSize={24}>{entries =>
<div className="atlas-arch-table-wrap"><table className="atlas-arch-table"><thead><tr><th scope="col">{text.name}</th><th scope="col">{text.source}</th></tr></thead>
<tbody>{entries.map((entry, index) => <tr key={`${entry.qualifiedName ?? entry.name}:${index}`}>
<td>{entry.name}</td><td><SourceLink path={entry.filePath} line={entry.line} name={entry.name} onNavigate={onNavigate} /></td>
</tr>)}</tbody></table></div>}
</Collection>
</section>;
if (view === 'routes') return <section><SectionHeading title={text.views.routes} note={text.routeNote} />
<Collection items={data.routes} empty={empty} pageSize={24}>{routes =>
<div className="atlas-arch-table-wrap"><table className="atlas-arch-table"><thead><tr>
{[text.method, text.path, text.handler, text.evidence, text.source].map(label => <th scope="col" key={label}>{label}</th>)}
</tr></thead><tbody>{routes.map((route, index) => <tr key={`${route.method}:${route.path}:${index}`}>
<td><span className="atlas-arch-badge">{route.method ?? text.unknown}</span></td><td>{route.path}</td>
<td>{route.handler ?? <span className="atlas-arch-muted">{text.unknown}</span>}</td>
<td><span className="atlas-arch-badge" data-origin={route.origin}>{route.origin === 'source' ? text.sourceOrigin : text.indexOrigin}</span></td>
<td><SourceLink path={route.filePath} line={route.line} name={route.handler ?? route.path} onNavigate={onNavigate} /></td>
</tr>)}</tbody></table></div>}
</Collection>
</section>;
return <section><SectionHeading title={text.views.hotspots} note={text.hotspotNote} />
<Collection items={data.hotspots} empty={empty} pageSize={24}>{hotspots =>
<div className="atlas-arch-table-wrap"><table className="atlas-arch-table"><thead><tr>
{[text.name, text.fanIn, text.complexity, text.cognitive, text.loopDepth, text.signals, text.source].map(label => <th scope="col" key={label}>{label}</th>)}
</tr></thead><tbody>{hotspots.map((hotspot, index) => <tr key={`${hotspot.qualifiedName ?? hotspot.name}:${index}`}>
<td>{hotspot.name}</td>{[hotspot.fanIn, hotspot.complexity, hotspot.cognitive, hotspot.loopDepth].map((value, column) =>
<td key={column} className="atlas-arch-number">{value !== undefined ? value.toLocaleString() : <span className="atlas-arch-muted">{text.unknown}</span>}</td>)}
<td><HotspotSignals hotspot={hotspot} /></td>
<td><SourceLink path={hotspot.filePath} line={hotspot.line} name={hotspot.name} onNavigate={onNavigate} /></td>
</tr>)}</tbody></table></div>}
</Collection>
</section>;
}
const paletteStyle = scenePaletteStyle();
/** Compact exploration history beside the current scope. Tooltips name each destination. */
function HistoryControls({ history, place, onGo, onJump }: {
history: NavigationHistory<ArchitectureHistoryEntry>; place: ArchitectureHistoryEntry;
onGo: (step: -1 | 1) => void; onJump: (entry: ArchitectureHistoryEntry) => void;
}): JSX.Element {
const back = peekNavigation(history, -1), forward = peekNavigation(history, 1);
const here = architectureHistoryOptions.recentKey?.(place);
const menu = useDismissibleMenu(architectureHistoryOptions.key(place));
return <div className="atlas-arch-history" role="group" aria-label={historyText.group} data-position={`${history.index + 1}/${history.entries.length}`}>
<button type="button" aria-label={historyText.back} disabled={!back} onClick={() => onGo(-1)}
title={back ? historyText.backTo(architectureEntryLabel(back)) : historyText.noBack}>
<svg viewBox="0 0 20 20" aria-hidden="true"><path d="m12 5-5 5 5 5" /></svg></button>
<button type="button" aria-label={historyText.forward} disabled={!forward} onClick={() => onGo(1)}
title={forward ? historyText.forwardTo(architectureEntryLabel(forward)) : historyText.noForward}>
<svg viewBox="0 0 20 20" aria-hidden="true"><path d="m8 5 5 5-5 5" /></svg></button>
{history.recent.length > 1 && <details className="atlas-arch-recent" ref={menu.ref}>
<summary title={historyText.recentTitle} aria-label={historyText.recent}><svg viewBox="0 0 20 20" aria-hidden="true"><path d="M4 6a7 7 0 1 1-1 7M4 2v4H0m10 0v4l3 2" /></svg></summary>
<ul className="atlas-arch-recent-menu" aria-label={historyText.recentList}>{history.recent.map(entry => {
const id = architectureHistoryOptions.recentKey?.(entry);
const current = id === here;
const detail = architectureEntryDetail(entry);
return <li key={id}>
<button type="button" disabled={current} aria-current={current ? 'true' : undefined} title={architectureEntryLabel(entry)} onClick={() => {
menu.close();
onJump(entry);
}}><strong>{architectureEntryName(entry)}</strong>{detail && <span>{detail}</span>}</button>
</li>;
})}</ul>
</details>}
</div>;
}
function ArchitectureWorkspace({ projectName, overview, loading = false, error, onRefresh, onNavigate, graph, selectionPanel, onSelect, onClearSelection, onSelectionEvidence, graphNote, graphGeneration, active = true, escapeTaken = false, coverage, systemArchitectureLoader }: ArchitecturePanelProps): JSX.Element {
const storage = useMemo(browserStorage, []);
/*
* The place is the whole history entry (K27): subtab, opened area or file,
* route perspective and filter, System structure focus and groups, Behavior
* start, destination and position, and Plan or 3D of each scene. The views
* below read their part of it and report changes back, so Back and Forward
* restore every part at once. Only deliberate exploration adds a stop;
* tabs and display controls update the current visit. A filter saved by an earlier
* session would silently hide routes, so only the subtab is read back.
*/
const navigation = useArchitectureHistory(() => initialArchitecturePlace(readArchitectureConfig(storage, projectName).view), {
active, escapeTaken, onRestore: (from, to) => { if (from.view !== to.view) onSelectionEvidence?.(undefined); },
});
const { place, navigate } = navigation;
useEffect(() => { saveArchitectureConfig(storage, projectName, { view: place.view, filter: place.filter }); }, [place.view, place.filter, projectName, storage]);
const setView = useCallback((view: ArchitectureView) => navigate(current => ({ ...current, view: view === 'dependencies' ? 'overview' : view }), true), [navigate]);
const changeSpatial = useCallback<PlaceChange<SpatialPlace>>((change, automatic) =>
navigate(current => ({ ...current, spatial: { ...current.spatial, ...change } }), automatic), [navigate]);
const changeSystem = useCallback<PlaceChange<SystemPlace>>((change, automatic) =>
navigate(current => ({ ...current, system: { ...current.system, ...change } }), automatic), [navigate]);
const changePerspective = useCallback((routes: RoutesPerspective) => navigate(current => ({ ...current, routes }), true), [navigate]);
// Opening a route group is navigation; typing only refines the current visit.
const openRouteGroup = useCallback((filter: string) => navigate(current => ({ ...current, filter })), [navigate]);
// A cached summary from another project must never appear here.
const data = overview?.projectName && overview.projectName !== projectName ? undefined : overview;
const ready = Boolean(data && !loading && !error && projectName);
const systemView = place.view === 'structure' || place.view === 'behavior' ? place.view : undefined;
useEffect(() => {
if (active && (!projectName || (!systemView && (!ready || !graph)))) onSelectionEvidence?.(undefined);
}, [active, projectName, systemView, ready, graph, onSelectionEvidence]);
// Only the Routes view offers the filter, so no other view may receive a stale one.
const filter = place.view === 'routes' ? navigation.filter : '';
const historyControls = <HistoryControls history={navigation.history} place={place} onGo={navigation.go} onJump={navigation.jump} />;
const spatialProps = !systemView && ready && data && graph ? {
project: projectName, generation: graphGeneration, graph, overview: data,
view: place.view === 'dependencies' || place.view === 'structure' || place.view === 'behavior' ? 'overview' as const : place.view,
filter, onFilter: openRouteGroup, active, graphNote, coverage, onSelect, onClearSelection, onSelectionEvidence, selectionPanel, onNavigate, navigation: historyControls,
onView: (view: ArchitectureView) => { onSelectionEvidence?.(undefined); setView(view); }, place: place.spatial, onPlace: changeSpatial,
} : undefined;
// Every scene below draws with the same palette; the DOM reads it as CSS variables.
return <section className="atlas-architecture" data-testid="atlas-architecture" data-system-view={systemView} aria-label={text.title} aria-busy={!systemView && loading} style={paletteStyle}>
<div className="atlas-arch-tabrow">
<nav className="atlas-arch-tabs" aria-label={text.navigation}>{ARCHITECTURE_VIEWS.map(view =>
<button className="atlas-arch-tab" key={view} aria-pressed={place.view === view || (view === 'overview' && ['dependencies', 'entryPoints'].includes(place.view))} data-view={view}
onClick={() => { if (view !== place.view) onSelectionEvidence?.(undefined); setView(view); }}>{text.views[view]}</button>)}</nav>
</div>
{systemView && projectName ? <Suspense fallback={<div role="status"><Empty>Preparing system analysis…</Empty></div>}><SystemArchitecture
project={projectName} generation={graphGeneration} view={systemView} filter={filter} active={active}
graph={graph} onSelect={onSelect} onClearSelection={onClearSelection} onSelectionEvidence={onSelectionEvidence} onNavigate={onNavigate} loader={systemArchitectureLoader}
place={place.system} onPlace={changeSystem} navigation={historyControls} /></Suspense> : null}
{!systemView && !spatialProps && <div className="atlas-arch-context">{historyControls}<span>{projectName}</span></div>}
{!systemView && (!projectName ? <Empty>{text.chooseProject}</Empty> : loading ? <div role="status"><Empty>{text.loading}</Empty></div>
: error ? <div role="alert" className="atlas-arch-empty" data-error="true"><p>{text.loadFailed}</p><p className="atlas-arch-error-detail">{error}</p>
{onRefresh && <button className="atlas-arch-action" onClick={onRefresh}>{text.retry}</button>}</div>
: !data ? <Empty>{text.unavailable}</Empty> : null)}
{systemView && !projectName && <Empty>{text.chooseProject}</Empty>}
{spatialProps && place.view === 'routes' && <div className="atlas-arch-toolbar"><label className="atlas-arch-filter">
<svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><circle cx="6.5" cy="6.5" r="4.5" fill="none" stroke="currentColor" strokeWidth="1.4" /><path d="m10 10 4 4" stroke="currentColor" strokeWidth="1.4" /></svg>
<input aria-label={text.filter} placeholder={text.filterPlaceholder} type="search" value={navigation.filter} onChange={event => navigation.type(event.target.value)} /></label></div>}
{spatialProps && (place.view === 'routes'
? <RoutesArchitecture {...spatialProps} perspective={place.routes} onPerspective={changePerspective} />
: <SpatialArchitecture {...spatialProps} />)}
{!systemView && ready && data && !graph && <div className="atlas-arch-content" data-testid="atlas-architecture-content">
<p className="atlas-arch-fallback-summary">{data.files.length.toLocaleString()} files · {data.groups.length.toLocaleString()} source areas · {data.boundaries.length.toLocaleString()} cross-area connections</p>
<Findings view={place.view === 'overview' || place.view === 'dependencies' ? 'entryPoints' : place.view} data={data} empty={text.noData} onNavigate={onNavigate} />
</div>}
</section>;
}
/** A project switch remounts the workspace: a fresh history, as in Galaxy. */
export default function ArchitecturePanel(props: ArchitecturePanelProps): JSX.Element {
return <ArchitectureWorkspace key={props.projectName} {...props} />;
}