smarttools/docs/PROJECT.md

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

# 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

# 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

# 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.