181 lines
5.6 KiB
Markdown
181 lines
5.6 KiB
Markdown
# 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.
|