# CmdForge Project Overview

> **Document Status (January 2026)**: This overview is mostly accurate but the source structure
> section is outdated. The TUI has been replaced by a PySide6 GUI. Database now has 25+ tables.
> For current architecture, see `src/cmdforge/` directly.

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

## What is CmdForge?

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

1. **CLI Tool** (`cmdforge`) - 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/cmdforge/cli.py` | Main entry point for `cmdforge` command |
| Registry API | `src/cmdforge/registry/` | REST API for tool registry |
| Web UI | `src/cmdforge/web/` | Flask web application |
| Tool Storage | `~/.cmdforge/` | User's installed tools |
| Database | `data/cmdforge.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/cmdforge/
├── cli/                # CLI commands
│   ├── __init__.py     # Entry point, subcommand routing
│   └── registry_commands.py  # Registry CLI commands
├── tool.py             # Tool dataclasses, YAML loading
├── runner.py           # Step execution engine
├── providers.py        # AI provider abstraction
├── profiles.py         # AI persona profiles
├── config.py           # Global configuration
│
├── gui/                # PySide6 Desktop GUI (primary UI)
│   ├── main_window.py  # Main application window
│   ├── pages/          # Tools, Registry, Providers, Profiles pages
│   ├── dialogs/        # Step editors, Publish, Connect dialogs
│   └── workers/        # Background threads for API calls
│
├── registry/           # Registry API Server
│   ├── app.py          # Flask API with 100+ endpoints
│   ├── db.py           # Database operations, FTS5 search (25+ tables)
│   ├── rate_limit.py   # API rate limiting
│   ├── scrutiny.py     # Automated code analysis
│   ├── similarity.py   # Duplicate detection
│   └── sync.py         # Git sync for tool submissions
│
├── web/                # Web UI Application
│   ├── app.py          # Flask web app
│   ├── routes.py       # Page routes and handlers
│   ├── auth.py         # Password hashing, login/register
│   ├── sessions.py     # Session management
│   ├── forum/          # Forum blueprint
│   ├── templates/      # Jinja HTML templates
│   └── static/         # CSS (Tailwind), JS, images
│
└── registry_client.py  # CLI client for registry API
```

## Database Schema

SQLite database at `~/.cmdforge/registry.db` (or via `CMDFORGE_REGISTRY_DB` env var):

| Table | Purpose |
|-------|---------|
| `publishers` | User accounts with roles, banning, verification |
| `tools` | Published tools with moderation status, fork tracking |
| `api_tokens` | Authentication tokens for API access |
| `download_stats` | Tool download tracking by date |
| `reviews` | Tool reviews with 1-5 star ratings |
| `review_votes` | Helpful/unhelpful votes on reviews |
| `tool_issues` | Bug, security, compatibility issue reports |
| `collections` | Curated tool groups |
| `announcements` | Admin announcements |
| `featured_tools` | Featured tool placement |
| `featured_contributors` | Featured publisher placement |
| `reports` | Abuse reports for moderation |
| `audit_log` | Admin action audit trail |
| `pairing_requests` | App pairing flow |
| `web_sessions` | Session storage |
| `consents` | User consent for analytics/ads |
| `pageviews` | Analytics tracking |
| `tools_fts` | Full-text search index (FTS5) |
| `tool_stats` | Cached tool statistics |
| `publisher_stats` | Cached publisher statistics |
| `registry_settings` | Runtime-configurable settings |

## 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
- `~/.cmdforge/providers.yaml` - AI provider configurations
- `~/.cmdforge/config.yaml` - Global settings
- `~/.cmdforge/<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 cmdforge.cli

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

### Production

```bash
# Using gunicorn
gunicorn -w 4 -b 0.0.0.0:5050 'cmdforge.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=cmdforge
```

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