DBA-291 Refactor databao-cli: Phase 1

docs/architecture.md

@@ -1,68 +1,65 @@
 # 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:
+Project structure:
+```
+src/databao_cli/
+- commands/           # CLI commands
+- ui/                 # Web UI (Streamlit)
+- mcp/                # MCP server  
+- project/            # Project management
+- log/                # Logging
+```
 
-- 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/`)
+## 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
 
 ## Entry Point
-
-`databao_cli.__main__:cli` — a Click group that registers all subcommands.
+`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`.
 
 ## CLI Commands
+The CLI is implemented using the Click framework.
 
-| 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)
+### Structure
+- All CLI commands are located in `src/databao_cli/commands/`
+- Single command = single file.
+- Each command MUST be implemented in its own module.
+- File name SHOULD match the command name.
+- Grouped commands MUST be organized in subdirectories. Example: `src/databao_cli/commands/datasource/`
 
-`src/databao_cli/ui/` contains the Streamlit application:
+### Registration
+- All commands and groups MUST be explicitly registered in `src/databao_cli/__main__.py`
+- Commands and groups are exposed via the COMMANDS collection. Every new command or group MUST be added to this collection to be discoverable by the CLI.
 
-- `app.py` — main Streamlit entry
-- `pages/` — individual UI pages
-- `components/` — reusable UI components
-- `services/` — backend service wrappers
-- `models/` — data models for UI state
+## 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
-
-## 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.
+```
+src/databao_cli/mcp/  # exposes tools via the Model Context Protocol:
+  server.py           # FastMCP server setup
+  tools/              # individual tool handlers
+```
 
 ## Extension Points
-
-- Add CLI command: create module in `commands/`, register with Click group
-  in `__main__.py`.
+- Add CLI command: create module in `commands/`, then add it to the
+  `COMMANDS` collection in `src/databao_cli/__main__.py`.
 - Add MCP tool: add handler in `mcp/tools/`, register in `mcp/server.py`.
 - Add datasource type: extend via `databao-context-engine` optional deps.
 - Add UI page: add to `ui/pages/`.