STRUCTURE.md

VizAdvisor — Directory Structure

Reference for navigating the codebase. Last updated: February 2026

---

Root

File	Purpose
README.md	Project overview, setup, features
run.sh	One-command dev launcher
package.json	Dependencies, scripts
vite.config.js	Vite config, chunking, test setup
index.html	HTML entry, CSP
.env.example	Client env template
mermaid-map.md	Mermaid flowchart of repo structure
IMPLEMENTATION-PLAN.md	Phased build specification
CHANGELOG.md	Version history

---

src/

Entry & App

File	Purpose
main.jsx	React root, StrictMode
App.jsx	Providers, routing, theme wrapper, lazy-loaded pages

src/pages/

File	Route	Purpose
HomePage.jsx	/	Landing, intro, CTA to Advisor
AdvisorPage.jsx	/advisor	Main tool: input + output panels
AboutPage.jsx	/about	What the tool does, data handling

src/components/

layout/

File	Purpose
Header.jsx	Logo, nav (Advisor, About), theme toggle, GitHub link
Footer.jsx	Footer content
Sidebar.jsx	Optional history / saved sessions

input/

File	Purpose
DataUploader.jsx	CSV/JSON file drop or paste
DataPreview.jsx	Schema table, type override
GoalSelector.jsx	Goal category dropdown + description
ParameterPanel.jsx	Audience, library, interactivity, accessibility, notes
PromptBuilder.jsx	Submit / Reset buttons, readiness state

output/

File	Purpose
RecommendationList.jsx	Container: loading, error, or full recommendation view
RecommendationCard.jsx	Primary chart type, rationale, data mapping
AlternativeOptions.jsx	Alternative chart options
DesignDecisionsPanel.jsx	Color, scale, annotations, accessibility
PitfallWarnings.jsx	Pitfalls and mitigations
CodeSnippet.jsx	Syntax-highlighted code with copy
FollowUpQuestions.jsx	Suggested follow-up questions
ExportButton.jsx	Copy / download as Markdown or JSON
MetaBadges.jsx	Confidence, goal category badges

analysis/

File	Purpose
AnalysisPanel.jsx	Engine (R/Python), analysis type, config form, Run button
AnalysisResults.jsx	Renders analysis output

common/

File	Purpose
Button.jsx	Primary/secondary/ghost, loading state
Spinner.jsx	Loading indicator
Modal.jsx	Modal dialog
Tooltip.jsx	Tooltip
ErrorBanner.jsx	Error display with retry
CopyButton.jsx	Copy-to-clipboard
Badge.jsx	Badge/chip

src/hooks/

File	Purpose
useLLM.js	LLM request lifecycle: submit, status, recommendation, error
useDataParser.js	File parsing, schema inference
useSessionHistory.js	Save/load sessions from localStorage
useAnalysis.js	Pre/post analysis: run, status, results, error

src/services/

File	Purpose
llmService.js	LLM API calls, streaming, response parsing
dataService.js	CSV/JSON parsing via PapaParse
promptTemplates.js	System prompt, buildMessages, buildFollowUpMessages
analysisService.js	POST /api/analyze client

src/context/

File	Purpose
SessionContext.jsx	Dataset, goal, parameters, recommendation, analysis state
SettingsContext.jsx	Model, library, theme, verbosity (persisted)

src/utils/

File	Purpose
columnTypeInferrer.js	Infer quantitative, ordinal, nominal, temporal, geographic
chartTypeMapper.js	Map goal + data types → candidate chart types
formatters.js	Number, date, file size formatting
responseValidator.js	Validate LLM JSON response schema

src/styles/

File	Purpose
global.css	Tailwind imports, base styles
theme.js	Design tokens (colors, spacing)

---

server/

File	Purpose
index.js	Express app: CORS, /api/recommend, /api/analyze
.env.example	Server env template
requirements.txt	Python analysis dependencies

server/analysis/

File	Purpose
runner.js	Validate request, spawn R/Python, parse JSON stdout
README.md	R/Python setup, endpoint docs

server/analysis/r/

File	Purpose
descriptive.R	Descriptive statistics
regression.R	Linear regression / ANOVA
power.R	Power analysis
mediation.R	Mediation analysis
factorial.R	Factorial ANOVA

server/analysis/python/

File	Purpose
descriptive.py	Descriptive statistics
regression.py	Linear regression / ANOVA
power.py	Power analysis
mediation.py	Mediation analysis
factorial.py	Factorial ANOVA

---

tests/

Path	Purpose
setup.js	Vitest setup, jsdom
unit/	Unit tests for utils, services
integration/	AdvisorFlow integration test
prompts/	Golden-path JSON fixtures

---

docs/

File	Purpose
ARCHITECTURE.md	System design, layers, data flow
PROMPT-DESIGN.md	Prompt construction, output schema
DATA-VIZ-REFERENCE.md	Chart taxonomy, encoding principles
CONTRIBUTING.md	Contribution guidelines
STRUCTURE.md	This file
ROUTES.md	Routes and sitemap