Data Control Center

demo_v1_fast_h264.mp4

Local-first tool for profiling, exploring, and querying local data files (CSV, TSV, Parquet, JSON, JSON Lines, NDJSON, and DuckDB) with fast browse-and-import for .duckdb files via Import DuckDB (one system file dialog when native pick is enabled; HTTP upload remains for API/tests/fallback). A guided Overview, conservative relationship discovery, persistent charts, and ad-hoc DuckDB SQL support fast analysis on a single trusted workstation—not hosted BI or multi-tenant use. This app is local-only; see SECURITY.md for the threat model and vulnerability reporting.

Quick start (no LLM required)

1. From the repo root: make install then make dev (requires GNU bash; see Platform notes).
2. Open http://127.0.0.1:5173.
3. New here? Follow the 5-minute tour with examples/ fixtures before using your own data.

Start in Overview, verify suggested joins, save and download charts, then use Columns, Samples, or SQL for deeper exploration. Ask is optional and needs Ollama; see User guide — Ask.

Platform notes

• macOS — primary platform; Node 22 (.nvmrc), Python 3.11+, uv, optional Ollama.
• Linux — same make targets; install Node 22 and uv from your distro or upstream.
• Windows — use WSL2 (e.g. Ubuntu). Native Windows without WSL is untested.

Prerequisites: Node 22 from .nvmrc (matches CI). Python 3.11+ and uv. Run make help from the repo root for all targets.

Single-server mode

make serve

Opens http://127.0.0.1:8000 (API serves the built UI via DCC_UI_DIST_PATH). Day-to-day development uses make dev (Vite on 5173 + API on 8000).

Upgrading / workspace schema

Workspace metadata lives in DCC_WORKSPACE_DB_PATH (default .dcc_workspace.duckdb relative to the backend cwd). The current release extends compatible workspaces in place with saved-chart and relationship-decision tables before strict schema validation. This extension is forward-only and does not create an automatic backup. To downgrade, restore a pre-upgrade workspace copy or run make clean-local. That command removes app cache, saved work, Ask history, and upload copies under .dcc_uploads/, not original source files. Other incompatible layout or profile changes still fail fast; follow the applicable CHANGELOG upgrade notes. Schema details: backend/README.md.

Upgrading to 1.1.0

If you used 1.0.0, read CHANGELOG — 1.1.0 before upgrading. In short:

1. Update custom API clients: DuckDB inspect/import APIs use source_id (replaces upload_id).
2. /api/saved-charts was removed; saved chart rows are dropped from local workspaces on next startup.
3. Saved SQL snippets gain an optional description column; existing workspaces migrate in place on startup.
4. Large datasets may rebuild profiles with sample-scoped metrics; the UI polls prepare jobs until ready.

Upgrading to 1.0.0

If you used 0.1.0, read CHANGELOG — 1.0.0 before upgrading. In short:

1. make clean-local (or delete .dcc_workspace.duckdb) so the workspace and profile cache match the new schema.
2. Re-open datasets; profiling is async on first load (PROFILE_NOT_READY + job polling).
3. Custom Ask clients must call POST /api/agent/ask/stream only (sync ask removed).

1.0.0 also changes default UX: Ask runs a second Ollama summarization pass by default (set DCC_AGENT_SUMMARIZE_WITH_LLM=false for lower latency). Columns opens sorted by column name ascending; distribution stats show STDEV for standard deviation.

API reference

With the backend running: http://127.0.0.1:8000/docs (Swagger UI).

Architecture

• Frontend (frontend/): React, Vite, TypeScript, TanStack Query/Table, Zustand, ECharts, Tailwind, shadcn-style primitives
• Backend (backend/): FastAPI, DuckDB, Polars, Pydantic, uv

Documentation map

Document	Audience	Purpose
docs/README.md	Users	Index: tour vs user guide
docs/5-minute-tour.md	Users	First-run walkthrough with examples/
docs/user-guide.md	Users	Day-to-day usage, shortcuts, tabs
examples/README.md	Users	Synthetic fixture descriptions
CONTRIBUTING.md	Contributors	Setup, validation, pull requests
backend/README.md	Backend devs	API, DCC_* config, workspace
frontend/README.md	Frontend devs	Vite proxy, layout, TanStack conventions
AGENTS.md	AI agents	Agent rules; links to CONTRIBUTING for commands
SECURITY.md	Security	Threat model and vulnerability reporting
CHANGELOG.md	Upgraders	Breaking changes and release notes
docs/RELEASE.md	Maintainers	Tagging and GitHub Release steps
CODE_OF_CONDUCT.md	Community	Contributor Covenant

Known limitations (MVP)

• Excel and remote files are not supported yet.
• Relationship suggestions are conservative: they require matching key-like column names and compatible profiled types. Arbitrary manual and many-to-many relationship modeling is not included.
• Very wide files may be slow on first profile; use Refresh in the dataset strip or POST /api/datasets/{id}/profile/refresh.