Move docs to project-docs symlink structure

- Docs now point to project-docs/docs/projects/cmdforge - Old docs preserved in olddocs/ - Updated .gitignore to ignore docs symlink 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
2026-01-06 22:26:39 -04:00
parent 1caa3454f0
commit 9fbe45244d
11 changed files with 3 additions and 0 deletions
@@ -0,0 +1,180 @@
+# CmdForge Project Overview
+
+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.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/cmdforge.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
+- `~/.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.