[DBA-292] Refactor databao-cli: Phase 2

docs/architecture.md

@@ -1,68 +1,115 @@
 # Architecture
 
 ## Overview
-
 Databao CLI is a Python CLI application built with Click that provides a
 command-line and web interface to the Databao Agent and Context Engine.
 
-Key layers:
-
-- CLI commands (`src/databao_cli/commands/`)
-- Web UI via Streamlit (`src/databao_cli/ui/`)
-- MCP server (`src/databao_cli/mcp/`)
-- Project management (`src/databao_cli/project/`)
-- Logging (`src/databao_cli/log/`)
-
-## Entry Point
-
-`databao_cli.__main__:cli` — a Click group that registers all subcommands.
-
-## CLI Commands
-
-| Command              | Module                          | Purpose                         |
-|----------------------|---------------------------------|---------------------------------|
-| `databao init`       | `commands/init.py`              | Initialize a new project        |
-| `databao status`     | `commands/status.py`            | Show project status             |
-| `databao datasource` | `commands/datasource/`          | Add/check data sources          |
-| `databao build`      | `commands/build.py`             | Build context for datasources   |
-| `databao ask`        | `commands/ask.py`               | Interactive chat with agent     |
-| `databao app`        | `commands/app.py`               | Launch Streamlit web UI         |
-| `databao mcp`        | `commands/mcp.py`               | Run MCP server                  |
-
-## Web UI (Streamlit)
-
-`src/databao_cli/ui/` contains the Streamlit application:
-
-- `app.py` — main Streamlit entry
-- `pages/` — individual UI pages
-- `components/` — reusable UI components
-- `services/` — backend service wrappers
-- `models/` — data models for UI state
-
-## MCP Server
-
-`src/databao_cli/mcp/` exposes tools via the Model Context Protocol:
-
-- `server.py` — FastMCP server setup
-- `tools/` — individual tool handlers
+Project structure:
+```
+src/databao_cli/
+- commands/           # CLI routing layer (Click wrappers only)
+- workflows/          # Interactive CLI sequences (REPL, wizards, result display)
+- features/           # Business logic, organized by feature — no Click dependency
+- shared/             # Cross-feature utilities and models
+```
 
 ## Key Dependencies
-
 - `databao-context-engine` — core context indexing and querying
 - `databao-agent` — AI agent for natural language interaction
 - `click` — CLI framework
 - `streamlit` — web UI framework
 - `fastmcp` — MCP server framework
 
-## Database Support
-
-Multi-database via optional dependencies: Snowflake (default), BigQuery,
-ClickHouse, Athena, MS SQL, with ADBC drivers.
+## Entry Point
+`databao_cli.__main__:cli` — a Click group that registers all subcommands and
+is exposed as the `databao` console script (run as `databao ...` after installation).
+During development, it can also be invoked via `uv run databao`.
+
+## Layer Responsibilities
+
+### `commands/` — Routing Layer
+Contains only Click wiring: decorators, option/argument definitions, and calls
+to workflow or feature functions. No business logic lives here.
+
+- Single command = single file; file name MUST match the command name.
+- Grouped commands MUST be organized in subdirectories (e.g. `commands/datasource/`).
+- All commands and groups MUST be registered in `src/databao_cli/__main__.py`
+  via the `COMMANDS` collection.
+
+### `workflows/` — Interactive CLI Layer
+Interactive CLI sequences that need multi-step user interaction (prompts,
+confirmations, REPL loops) or result display. Uses Click freely. Calls into
+`features/` for business operations. Complex workflows get a subdirectory;
+thin workflows are a single file.
+
+```
+workflows/
+  ask.py              # run_interactive_mode, run_one_shot_mode, display_result
+  datasource/
+    add.py            # add_workflow (interactive wizard: prompts, confirms, echoes)
+    check.py          # print_connection_check_results
+```
+
+Commands that require no interaction (build, index, status) skip this layer and
+call `features/` directly.
+
+### `features/` — Business Logic Layer
+All application logic lives here, organized by feature. No Click dependency —
+`features/` functions are pure business operations callable from any context
+(CLI, MCP, tests). Complex features get a subdirectory; thin features are a
+single file.
+
+```
+features/
+  ask/
+    agent_factory.py  # initialize_agent_from_dce — returns Agent
+    display.py        # dataframe_to_prettytable (pure formatter, returns str)
+    service.py        # ask_impl — validates args, initialises agent
+  init/
+    errors.py         # project initialization error types
+    service.py        # init_impl, _ProjectCreator
+  datasource/
+    add.py            # datasource_config_exists, create_datasource_config
+    check.py          # check_impl — returns connection results dict
+  mcp/
+    server.py         # FastMCP server setup, mcp_impl
+    tools/            # individual MCP tool handlers
+  ui/
+    app.py            # main Streamlit entry point
+    cli.py            # bootstrap_streamlit_app, app_impl
+    pages/            # individual UI pages
+    components/       # reusable UI components
+    services/         # backend service wrappers
+    models/           # data models for UI state
+    streaming.py      # streaming writer for real-time output
+    project_utils.py  # project status helpers used across features
+    suggestions.py    # suggested questions logic
+  build.py            # build_impl
+  index.py            # index_impl
+  status.py           # status_impl, info string generation
+```
+
+### `shared/` — Shared Utilities
+Cross-feature code with no business logic of its own.
+
+```
+shared/
+  project/
+    layout.py         # ProjectLayout dataclass, find_project
+  log/
+    logging.py        # configure_logging
+    llm_errors.py     # format_llm_error (user-friendly API error messages)
+  cli_utils.py        # get_project_or_raise, handle_feature_errors
+  context_engine_cli.py  # ClickUserInputCallback (Click ↔ DCE adapter)
+  executor_utils.py   # build_llm_config, LLM provider/model constants
+  errors.py           # FeatureError
+```
 
 ## Extension Points
-
-- Add CLI command: create module in `commands/`, register with Click group
-  in `__main__.py`.
-- Add MCP tool: add handler in `mcp/tools/`, register in `mcp/server.py`.
+- Add CLI command: create module in `commands/`, then add it to the
+  `COMMANDS` collection in `src/databao_cli/__main__.py`.
+- Add interactive workflow: create module in `workflows/`, call from command.
+- Add MCP tool: add handler in `features/mcp/tools/`, register in
+  `features/mcp/server.py`.
 - Add datasource type: extend via `databao-context-engine` optional deps.
-- Add UI page: add to `ui/pages/`.
+- Add UI page: add to `features/ui/pages/`.

examples/demo-snowflake-project/src/databao_snowflake_demo/app.py

@@ -6,7 +6,7 @@
 
 import streamlit as st
 
-from databao_cli.ui.app import main
+from databao_cli.features.ui.app import main
 
 logger = logging.getLogger(__name__)