# SmartTools Project Overview

This document provides a comprehensive overview of the SmartTools project structure, components, and how everything fits together.

## What is SmartTools?

SmartTools is a personal tool builder for AI-powered CLI commands. It consists of three main components:

1. **CLI Tool** (`smarttools`) - Create, manage, and run AI-powered command-line tools
2. **Registry API** - REST API for publishing and discovering tools
3. **Web UI** - Browser interface for the registry with docs, search, and user dashboard

## Quick Reference

| Component | Location | Purpose |
|-----------|----------|---------|
| CLI | `src/smarttools/cli.py` | Main entry point for `smarttools` command |
| Registry API | `src/smarttools/registry/` | REST API for tool registry |
| Web UI | `src/smarttools/web/` | Flask web application |
| Tool Storage | `~/.smarttools/` | User's installed tools |
| Database | `data/smarttools.db` | SQLite with FTS5 search |

## Architecture Diagrams

See `docs/diagrams/` for visual representations:

- **system-architecture.svg** - How components interact
- **deployment-architecture.svg** - Production deployment setup
- **source-organization.svg** - Code structure

## Source Code Structure

```
src/smarttools/
├── cli.py              # Entry point, subcommand routing
├── tool.py             # Tool dataclasses, YAML loading
├── runner.py           # Step execution engine
├── providers.py        # AI provider abstraction
├── config.py           # Global configuration
├── manifest.py         # Tool manifest handling
│
├── registry/           # Registry API Server
│   ├── app.py          # Flask API application
│   ├── db.py           # Database operations, FTS5 search
│   ├── rate_limit.py   # API rate limiting
│   ├── sync.py         # Git sync for tool submissions
│   ├── categorize.py   # Auto-categorization
│   └── similarity.py   # Similar tool recommendations
│
├── web/                # Web UI Application
│   ├── app.py          # Flask web app, Sentry integration
│   ├── routes.py       # Page routes and handlers
│   ├── auth.py         # Password hashing, login/register
│   ├── sessions.py     # Session management
│   ├── docs_content.py # Documentation text content
│   ├── seo.py          # Sitemap, robots.txt
│   ├── filters.py      # Jinja template filters
│   ├── templates/      # Jinja HTML templates
│   └── static/         # CSS, JS, images
│
├── registry_client.py  # CLI client for registry API
├── resolver.py         # Dependency resolution
│
├── ui.py               # TUI dispatcher
├── ui_urwid.py         # urwid TUI implementation
└── ui_snack.py         # newt/snack TUI fallback
```

## Database Schema

SQLite database at `data/smarttools.db`:

| Table | Purpose |
|-------|---------|
| `publishers` | User accounts (username, email, password_hash) |
| `tools` | Published tools (name, owner, description, config) |
| `api_tokens` | Authentication tokens for API access |
| `download_stats` | Tool download tracking |
| `pageviews` | Analytics for tool detail pages |
| `tools_fts` | Full-text search index (FTS5) |

## API Endpoints

Base URL: `/api/v1/`

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/tools` | GET | List/search tools |
| `/tools/<owner>/<name>` | GET | Get tool details |
| `/tools/<owner>/<name>` | POST | Publish tool (auth required) |
| `/tools/<owner>/<name>/download` | POST | Record download |
| `/me` | GET | Current user info |
| `/tokens` | GET/POST | Manage API tokens |

## Web Routes

| Route | Purpose |
|-------|---------|
| `/` | Homepage with featured tools |
| `/tools` | Tool browser with search |
| `/tools/<owner>/<name>` | Tool detail page |
| `/docs/*` | Documentation pages |
| `/login`, `/register` | Authentication |
| `/dashboard/*` | User dashboard, token management |

## Key Files to Know

### Configuration
- `~/.smarttools/providers.yaml` - AI provider configurations
- `~/.smarttools/config.yaml` - Global settings
- `~/.smarttools/<tool>/config.yaml` - Individual tool configs

### Development
- `pyproject.toml` - Package configuration
- `pytest.ini` - Test configuration
- `tailwind.config.js` - Tailwind CSS configuration

### Documentation
- `docs/REGISTRY.md` - Registry design document (comprehensive)
- `docs/WEB_UI.md` - Web UI design document (comprehensive)
- `wiki/Home.md` - User-facing wiki documentation
- `CLAUDE.md` - Development guidance for AI assistants

## Running the Project

### Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run CLI
python -m smarttools.cli

# Run web server (development)
cd src/smarttools/web
flask run --port 5050
```

### Production

```bash
# Using gunicorn
gunicorn -w 4 -b 0.0.0.0:5050 'smarttools.web.app:create_app()'

# Environment variables needed:
# FLASK_ENV=production
# SECRET_KEY=<your-secret-key>
# SENTRY_DSN=<optional-sentry-dsn>
# SITE_URL=https://your-domain.com
```

### systemd Service

See `docs/DEPLOYMENT.md` for systemd service configuration.

## Testing

```bash
# Run all tests
pytest

# Run specific test
pytest tests/test_name.py::test_function

# Run with coverage
pytest --cov=smarttools
```

## Design Documents

For detailed design decisions and specifications:

- **docs/REGISTRY.md** - Complete registry API design (Phases 1-8)
- **docs/WEB_UI.md** - Complete web UI design (Phase 7)
- **wiki/Home.md** - User documentation for CLI usage

## Archive

Old development discussions and diagrams are preserved in `archive/discussions/` for historical reference.