file-map.md

File Map — Where Does X Live?

A lookup table from features, routes, components, and concerns to their source path and the doc that covers them. Optimized for fast "where is this?" navigation.

Paths are relative to the repo root. When in doubt, this map is the fastest way to jump from a feature name to the code and the relevant documentation.

Pages (routes → source → doc)

Route	Source	Doc
/ (Dashboard)	app/page.tsx	pages.md
/database	app/database/page.tsx	pages.md
/schema	app/schema/page.tsx	pages.md
/query	app/query/page.tsx	pages.md
/history	app/history/page.tsx	pages.md
/learning	app/learning/page.tsx	pages.md
/reports	app/reports/page.tsx	pages.md
/profile	app/profile/page.tsx	pages.md
/admin	app/admin/page.tsx	pages.md
/landing	app/landing/page.tsx	pages.md
/auth/login	app/auth/login/page.tsx	pages.md
Root layout	app/layout.tsx	pages.md

API Routes (route → source → doc)

Route	Source	Doc
/api/query/generate	app/api/query/generate/route.ts	query-endpoints.md
/api/query/execute	app/api/query/execute/route.ts	query-endpoints.md
/api/query/cancel	app/api/query/cancel/route.ts	query-endpoints.md
/api/query/enhance	app/api/query/enhance/route.ts	query-endpoints.md
/api/query/revise	app/api/query/revise/route.ts	query-endpoints.md
/api/query/followup	app/api/query/followup/route.ts	query-endpoints.md
/api/schema/introspect	app/api/schema/introspect/route.ts	schema-endpoints.md
/api/schema/start-introspection	app/api/schema/start-introspection/route.ts	schema-endpoints.md
/api/schema/status	app/api/schema/status/route.ts	schema-endpoints.md
/api/schema/cancel-introspection	app/api/schema/cancel-introspection/route.ts	schema-endpoints.md
/api/schema/upload-schema	app/api/schema/upload-schema/route.ts	schema-endpoints.md
/api/schema/generate-descriptions	app/api/schema/generate-descriptions/route.ts	schema-endpoints.md
/api/schema/update-description	app/api/schema/update-description/route.ts	schema-endpoints.md
/api/schema/sample-data	app/api/schema/sample-data/route.ts	schema-endpoints.md
/api/dashboard/suggestions	app/api/dashboard/suggestions/route.ts	dashboard-endpoints.md
/api/chart/generate	app/api/chart/generate/route.ts	dashboard-endpoints.md
/api/connection/test	app/api/connection/test/route.ts	data-endpoints.md
/api/data/*	app/api/data/**/route.ts	data-endpoints.md
/api/admin/*	app/api/admin/**/route.ts	data-endpoints.md
/api/sharing/*	app/api/sharing/**/route.ts	data-endpoints.md
/api/config/*	app/api/config/**/route.ts	data-endpoints.md
/api/auth/[...nextauth]	app/api/auth/[...nextauth]/route.ts	data-endpoints.md

Features (feature → key source → doc)

Feature	Key source	Doc
State management (context)	lib/database-connection-options.tsx	state-management.md
Storage abstraction	lib/storage/storage-provider.ts (+ local/api impls)	auth-and-data-layer.md
Auth / OIDC	lib/auth/auth-options.ts, lib/auth/require-auth.ts	auth-and-data-layer.md
App DB pool	lib/db/pool.ts	auth-and-data-layer.md
Migrations	lib/db/migrations/*.sql, lib/db/migrate.ts, instrumentation.ts	auth-and-data-layer.md
Repositories	lib/db/repositories/*.ts	auth-and-data-layer.md
Password encryption	lib/db/encryption.ts	auth-and-data-layer.md
Credential resolution	lib/database/connection-validator.ts	auth-and-data-layer.md
Database adapters	lib/database/adapters/*.adapter.ts, lib/database/factory.ts	adding-database-support.md
SQL dialect queries	lib/database/queries/*.queries.ts	adding-database-support.md
Read-only SQL validator (AST)	lib/database/sql-validator.ts (validateReadOnlySql, heuristicReadOnly fallback)	query-endpoints.md
Query audit log	lib/query-log.ts (logQuery), lib/query-log-file.ts, lib/db/repositories/query-log-repository.ts	auth-and-data-layer.md
Learn-from-queries (corrections + few-shot)	utils/schema-fingerprint.ts, utils/example-relevance.ts, utils/query-corrections.ts, app/api/query/generate/route.ts (buildLearningSections), lib/db/repositories/query-correction-repository.ts, app/api/data/corrections/route.ts (+ [id])	query-endpoints.md
OpenAI integration	lib/openai/schema-upload.ts, query/schema routes	openai-integration.md
Reasoning effort (gpt-5 / o-series only)	app/api/query/generate/route.ts (REASONING_EFFORTS, asReasoningEffort; env OPENAI_REASONING_EFFORT)	query-endpoints.md
Model / effort request override (eval-only)	app/api/query/generate/route.ts (modelOverride, effortOverride; gated on env EVAL_ALLOW_MODEL_OVERRIDE=true)	evals/README.md
Token usage reporting (cost accounting)	app/api/query/generate/route.ts (usage field on the generate response — generate route only)	query-endpoints.md
Rate limiting	utils/rate-limiter.ts	api/overview.md
BYOK (user API key)	hooks/use-openai-key.tsx, hooks/use-openai-fetch.tsx	infrastructure.md
Error sanitization	utils/error-sanitizer.ts	openai-integration.md
Schema change detection	utils/compare-schemas.ts	pages.md
Dashboard metric status/formatting	utils/metric-status.ts	features.md
Report parameter substitution	utils/substitute-params.ts	features.md
API response helpers	lib/api/response.ts	data-endpoints.md

Components (component → file → doc)

Component	File	Doc
SchemaExplorer	components/schema-explorer.tsx	features.md
SchemaUpdateModal	components/schema-update-modal.tsx	features.md
QueryResultsDisplay	components/query-results-display.tsx	features.md
QueryTabContent	components/query-tab-content.tsx	features.md
DirtyReadToggle	components/dirty-read-toggle.tsx	query-endpoints.md
FollowupDialog	components/followup-dialog.tsx	features.md
ChartDisplay + charts/	components/chart-display.tsx, components/charts/*	features.md
ComposedChart	components/charts/composed-chart.tsx	features.md
ChartCustomizer	components/chart-customizer.tsx	features.md
Report components	components/save-report-dialog.tsx, edit-report-dialog.tsx, parameter-config.tsx, parameter-input-dialog.tsx, saved-reports.tsx	features.md
Export / Import Reports	components/export-reports-dialog.tsx, components/import-reports-dialog.tsx	features.md
Dashboard widgets (KPIs / trend chart)	components/executive-metrics.tsx, components/performance-chart.tsx, app/page.tsx (loadDashboardWidgets)	features.md
Query accuracy stat / override	app/page.tsx (stat card), components/query-tab-content.tsx (thumbs), lib/database-connection-options.tsx (recordQueryOutcome/overrideQueryOutcome), lib/db/repositories/query-accuracy-repository.ts, app/api/data/query-accuracy/route.ts, models/query-accuracy.interface.ts	—
Dashboard (demo) components	components/quick-actions.tsx, recent-reports.tsx, scheduled-reports.tsx, report-templates.tsx	features.md
Providers	components/auth-provider.tsx, openai-api-provider.tsx, theme-provider.tsx	infrastructure.md
ContentLoadingGate / ErrorBoundary	components/content-loading-gate.tsx, error-boundary.tsx	infrastructure.md
Navigation / Theme	components/navigation.tsx, theme-toggle.tsx	infrastructure.md
ShareDialog / DataMigrationDialog	components/share-dialog.tsx, data-migration-dialog.tsx	infrastructure.md
ConfirmationModal	components/confirmation-modal.tsx	infrastructure.md
API key (BYOK) UI	components/api-key-dialog.tsx, api-key-indicator.tsx	infrastructure.md

Models & Hooks

Item	File	Doc
TypeScript interfaces	models/*.interface.ts, models/common-types.ts	models/overview.md
QueryAccuracy / QueryCorrection	models/query-accuracy.interface.ts, models/query-correction.interface.ts	models/overview.md
DashboardWidgetConfig + SavedReport.visualization	models/saved-report.interface.ts	features.md
ComposedChartConfig + CHART_TOOLS	models/chart-config.interface.ts	features.md
Custom hooks	hooks/use-*.ts(x)	components/overview.md

Eval Harness (evals/)

Standalone NL→SQL evaluation harness — a tsx CLI (pnpm eval) that checks whether generated SQL executes and returns results matching authored golden SQL, across models, reasoning efforts, latency, and cost. Full usage: evals/README.md.

Item	File	Notes
Runner (CLI entry)	evals/run-eval.ts	Invoked by the eval package script (tsx evals/run-eval.ts)
Question dataset	evals/dataset.ts	32 questions: core 16 + extended 16
Golden-SQL verifier	evals/verify-goldens.ts	Checks the authored golden queries run against the target DB
Pricing rates	evals/pricing.json	USD per 1M tokens; ships with NULL rates, so cost renders as "—" until filled in
Shared types	evals/types.ts	Result/run shapes used across the harness
API client	evals/lib/api-client.ts	Typed fetch wrappers over the running dev server (generate sends model / effort, plus execute / introspect)
Failure classification	evals/lib/classify.ts	Classifies generate + execute failures (incl. mock-fallback / JSON-parse-fallback signals)
Result comparison	evals/lib/compare.ts (tests: tests/unit/compare.test.ts)	Compares generated vs golden result sets per the question's comparison mode
Cost accounting	evals/lib/pricing.ts	Applies pricing.json rates to reported token usage (breakdowns are subsets, never additive)
HTML report builder	evals/lib/report.ts	Builds the self-contained HTML report (no dependencies)
Schema vector store	evals/lib/vector-store.ts	Standalone schema upload + ingestion wait; mirrors lib/openai/schema-upload.ts without importing it
Run output (gitignored)	evals/results/*.jsonl, evals/results/*.html	Per-run raw records plus the HTML report

---

Related Documentation

• Documentation Index
• Architecture Overview
• API Overview