diff --git a/README.md b/README.md index 9b63eba..059a5f9 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ > **Stop writing documentation. Start generating it.** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) +[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) **The AI-powered documentation framework that lives inside your IDE.** Generate Architecture Decision Records, system diagrams, and onboarding guides with simple slash commands. No installations, no setup, no excuses. @@ -30,6 +30,32 @@ **Result:** Professional documentation that would take hours to write, generated in seconds. +## ๐Ÿ“ธ **Visual Showcase** + +### ๐Ÿ—๏ธ System Architecture Documentation + +Auto-generated architecture overview with intelligent component mapping: + +![System Architecture Example](images/system-architecture-example.png) + +### ๐Ÿš€ Onboarding Guide Generation + +Context-aware onboarding documentation tailored to your project: + +![Onboarding Doc Example](images/onboarding-doc-example.png) + +### ๐Ÿ“‹ Advanced Onboarding Features + +Comprehensive setup guides with framework-specific instructions: + +![Onboarding Doc Example 2](images/onboarding-doc-example-2.png) + +### ๐Ÿ—‚๏ธ Data Model Generation + +Professional ER diagrams and database schema documentation: + +![Data Model Generation](images/data-model-generation.png) + --- ## ๐Ÿš€ **Quick Start** *(2 minutes to awesome docs)* diff --git a/docs/architecture.md b/docs/architecture.md index 7bd1581..5f28949 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,7 +1,117 @@ +## System Architecture + +The `ai-cursor-init` project is an AI-powered documentation framework designed to work seamlessly within Cursor IDE and as a standalone CLI tool. + +### High-Level Architecture + ```mermaid graph TD - docs["Project documentation"] - cli["Command-line interface"] - templates["Template files"] - templates --> docs + A[Cursor IDE Integration] --> B[Slash Commands] + B --> C[AI Service Layer] + C --> D[Template Engine] + C --> E[Framework Detection] + C --> F[Diagram Generation] + + G[CLI Tool] --> C + + D --> H[Documentation Files] + E --> I[Project Analysis] + F --> J[Mermaid Diagrams] + + C --> K[Multi-Provider AI] + K --> L[OpenAI] + K --> M[Anthropic] + K --> N[Gemini] + + H --> O[Architecture Docs] + H --> P[ADRs] + H --> Q[Onboarding Guides] + H --> R[ER Diagrams] ``` + +### Core Components + +#### 1. **AI Service Layer** + +- **Purpose:** Centralized AI integration with multiple providers +- **Key Files:** `cli/cursor_init/ai_service.py`, `cli/cursor_init/ai_config.py` +- **Responsibilities:** + - Multi-provider AI support (OpenAI, Anthropic, Gemini) + - Context-aware documentation generation + - Intelligent code analysis and content updates + +#### 2. **Framework Detection Engine** + +- **Purpose:** Automatically detect project technologies and frameworks +- **Key Files:** `cli/cursor_init/detect_framework.py` +- **Capabilities:** + - Python framework detection (FastAPI, Django, Flask) + - JavaScript/TypeScript framework detection (React, Next.js) + - SQLAlchemy model detection for ER diagrams + - Project structure analysis + +#### 3. **Template System** + +- **Purpose:** Flexible, framework-aware documentation templates +- **Key Files:** Template files in `.cursor/templates/` +- **Features:** + - Multiple template variants per document type + - Framework-specific customization + - AI-powered content generation from templates + +#### 4. **Diagram Generation** + +- **Purpose:** Automated visual documentation creation +- **Key Files:** `cli/cursor_init/generate_diagrams.py` +- **Outputs:** + - ER diagrams from SQLAlchemy models + - Architecture diagrams from project structure + - Version-controlled Mermaid diagrams + +#### 5. **CLI Interface** + +- **Purpose:** Command-line tool for CI/CD integration +- **Key Files:** `cli/cursor_init/__main__.py` +- **Commands:** + - `init` - Initialize documentation structure + - `update` - AI-powered documentation updates + - `adr` - Create Architecture Decision Records + - `check-docs` - Validate documentation freshness + +#### 6. **Cursor IDE Integration** + +- **Purpose:** Seamless in-IDE documentation workflow +- **Key Files:** Rules in `.cursor/rules/` +- **Slash Commands:** + - `/init-docs` - Initialize project documentation + - `/update-docs` - Update existing documentation + - `/adr "Title"` - Create new ADRs + - `/gen-er-diagram` - Generate ER diagrams + - `/gen-arch-diagram` - Generate architecture diagrams + +### Data Flow + +1. **User Interaction:** Via Cursor slash commands or CLI +2. **Project Analysis:** Framework detection and code analysis +3. **AI Processing:** Context-aware content generation +4. **Template Application:** Framework-specific template selection +5. **Content Generation:** AI-enhanced documentation creation +6. **File Management:** Automated file creation and updates + +### Technology Stack + +- **Language:** Python 3.12+ +- **AI Providers:** OpenAI, Anthropic, Google Gemini +- **Diagram Format:** Mermaid (version-controlled, text-based) +- **Configuration:** YAML-based settings +- **IDE Integration:** Cursor rules and templates +- **Package Management:** pip/setuptools with pyproject.toml + +### Design Principles + +- **Documentation as Code:** Version-controlled alongside source code +- **AI-Enhanced:** Intelligent content generation and updates +- **Framework-Aware:** Automatic detection and customization +- **Zero-Installation:** Works out-of-the-box in Cursor IDE +- **CI-Friendly:** Automated validation and freshness checks +- **Multi-Provider:** Flexible AI backend support diff --git a/docs/data-model.md b/docs/data-model.md index e792ec2..146b4df 100644 --- a/docs/data-model.md +++ b/docs/data-model.md @@ -1,20 +1,87 @@ # Project Data Model -This document contains the Entity Relationship Diagram (ERD) for the project's data model. +This document describes the data structures and configuration models used by the AI-cursor-init framework. + +## Configuration Data Model + +The ai-cursor-init framework uses YAML-based configuration and dataclass models for managing settings and project metadata. ```mermaid erDiagram - users { - id int - username string - email string - created_at datetime + AIConfig { + provider string "openai|anthropic|gemini" + api_key string + model string + base_url string + temperature float + max_tokens int + } + + ProjectFrameworks { + languages set "python|typescript|javascript" + frameworks set "fastapi|django|react|nextjs|sqlalchemy" + root_directory string } - orders { - id int - user_id int - total_amount int - created_at datetime + + TemplateConfig { + template_paths dict + custom_template_paths dict + variant_preferences dict } - orders ||--o{ users : references + + DocumentationFile { + filepath string + content_type string "adr|architecture|onboarding|data-model" + last_updated datetime + template_used string + ai_generated boolean + } + + AIConfig ||--|| ProjectFrameworks : "configures generation for" + TemplateConfig ||--o{ DocumentationFile : "templates generate" + ProjectFrameworks ||--o{ DocumentationFile : "influences content of" ``` + +## Key Data Structures + +### AI Provider Configuration + +- **Purpose:** Manages multi-provider AI integration settings +- **Location:** Stored in project-local `.ai-cursor-init.yaml` or user config +- **Supported Providers:** OpenAI, Anthropic Claude, Google Gemini + +### Framework Detection Results + +- **Purpose:** Stores detected project technologies and frameworks +- **Usage:** Influences template selection and content generation +- **Detection Sources:** File analysis, dependency scanning, structure patterns + +### Template Metadata + +- **Purpose:** Maps document types to available templates and variants +- **Customization:** Supports custom template paths and user preferences +- **Inheritance:** Default templates can be overridden by project-specific ones + +### Documentation Tracking + +- **Purpose:** Maintains metadata about generated documentation files +- **Features:** Tracks AI generation status, template usage, and freshness +- **Integration:** Used by `/check-docs` for validation and staleness detection + +## File-Based Data Storage + +This project primarily uses file-based storage rather than traditional databases: + +- **Configuration Files:** YAML format for settings and preferences +- **Documentation Files:** Markdown format with embedded Mermaid diagrams +- **Template Files:** Jinja2-style templates with framework-specific variants +- **Metadata:** Embedded in file headers and configuration sections + +## Data Flow Pattern + +1. **Configuration Loading:** Read user/project AI and template settings +2. **Project Analysis:** Scan codebase to detect frameworks and structure +3. **Template Selection:** Choose appropriate templates based on detected frameworks +4. **AI Context Building:** Aggregate project information for AI providers +5. **Content Generation:** Generate documentation using AI + templates +6. **File Management:** Write/update documentation files with metadata tracking diff --git a/docs/onboarding.md b/docs/onboarding.md index e168f08..342033c 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -1,121 +1,168 @@ -# Project Onboarding Guide +# AI-Cursor-Init Project Onboarding Guide -This guide provides essential information for new team members joining the [Project Name] project. It covers the project's goals, team practices, development environment setup, and key resources. +This guide provides essential information for contributors to the AI-Cursor-Init project - an AI-powered documentation framework for Cursor IDE. ## Overview and Goals -* **Project Name:** [Project Name] -* **Purpose:** [Briefly describe the main purpose and vision of the project.] +* **Project Name:** AI-Cursor-Init +* **Purpose:** Provide an AI-powered documentation framework that works seamlessly within Cursor IDE and as a standalone CLI tool * **Key Goals:** - * [Goal 1: e.g., Deliver a robust backend API for the mobile application.] - * [Goal 2: e.g., Maintain a highly available and scalable service.] + * Enable intelligent documentation generation using multiple AI providers (OpenAI, Anthropic, Gemini) + * Provide framework-aware documentation templates and content generation + * Offer seamless integration with Cursor IDE through slash commands + * Support automated diagram generation (ER diagrams, architecture diagrams) + * Maintain documentation freshness through CI-friendly validation tools ## Contacts -* **Team Lead:** [Name/Contact Info] -* **Primary Backend Contact:** [Name/Contact Info] -* **Primary Frontend Contact:** [Name/Contact Info] -* **General Inquiries/Support:** [e.g., #project-support Slack channel] +* **Primary Maintainer:** [GitHub: @mgiovani](https://github.com/mgiovani) +* **Email:** +* **Issues:** [GitHub Issues](https://github.com/mgiovani/ai-cursor-init/issues) +* **Repository:** [GitHub Repository](https://github.com/mgiovani/ai-cursor-init) -## Team Practices +## Development Philosophy -* **Code Style:** We follow [e.g., PEP 8 for Python, Airbnb style guide for TypeScript]. Linting and formatting are enforced via [e.g., Black, ESLint, Prettier]. -* **Version Control:** We use Git with a [e.g., trunk-based development, GitFlow] branching strategy. All changes go through pull requests (PRs). -* **Code Reviews:** All code requires at least [number] approvals before merging. -* **Daily Stand-ups:** [Time, platform: e.g., 9:30 AM daily on Google Meet] -* **Communication:** [e.g., Primary communication on Slack, longer discussions on Google Meet, decisions documented in ADRs.] +* **Code Quality:** Follow PEP 8 for Python. Use type hints, single quotes, and avoid unnecessary comments/docstrings +* **Version Control:** Use Git with feature branches. All changes go through pull requests +* **Code Reviews:** All code requires review before merging +* **Testing:** Write unit tests for critical business logic; ensure tests are isolated and fast +* **AI Integration:** Responsible AI usage with proper error handling and user consent ## Development Environment Setup -Follow these steps to set up your local development environment: - ### Prerequisites -* [Prerequisite 1: e.g., Python 3.9+] -* [Prerequisite 2: e.g., Node.js 18+ and npm/yarn] -* [Prerequisite 3: e.g., Docker Desktop] -* [Prerequisite 4: e.g., PostgreSQL (local installation or via Docker)] +* **Python 3.12+** (required for modern typing features) +* **Git** for version control +* **Cursor IDE** (recommended for testing slash commands) +* **AI Provider API Keys** (optional, for testing AI features): + * OpenAI API key + * Anthropic API key + * Google Gemini API key -### Steps +### Setup Steps 1. **Clone the Repository:** ```bash - git clone [repository URL] - cd [project-directory] + git clone https://github.com/mgiovani/ai-cursor-init.git + cd ai-cursor-init + ``` + +2. **Set up Python Environment:** + + ```bash + # Create virtual environment + python3 -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + + # Install dependencies + pip install -r requirements.txt + + # Install in development mode + pip install -e ./cli + ``` + +3. **Configure AI Providers (Optional):** + + ```bash + # Create .env file with your API keys + cp .env.example .env + + # Edit .env with your API keys: + # OPENAI_API_KEY=your_openai_key_here + # ANTHROPIC_API_KEY=your_anthropic_key_here + # GEMINI_API_KEY=your_gemini_key_here ``` -2. **Backend Setup (Python/FastAPI Example):** - * **Create Virtual Environment:** +4. **Test the Installation:** + + ```bash + # Test CLI commands + ai-cursor-init --version + ai-cursor-init init + + # Test in Cursor IDE by opening the project and trying slash commands like: + # /init-docs + # /adr "Test ADR" + ``` - ```bash - python3 -m venv .venv - source .venv/bin/activate - ``` +## Project Structure - * **Install Dependencies:** +* **`/cli`:** Main CLI application source code + * `/cli/cursor_init`: Python package with core functionality + * `/cli/cursor_init/ai_service.py`: AI provider integration + * `/cli/cursor_init/detect_framework.py`: Framework detection logic + * `/cli/cursor_init/generate_diagrams.py`: Diagram generation +* **`/.cursor/rules`:** Cursor IDE integration rules for slash commands +* **`/.cursor/templates`:** Documentation templates organized by type +* **`/docs`:** Project documentation (this serves as an example) + * `/docs/adr`: Architecture Decision Records + * `/docs/development`: Development guides and patterns +* **`/tests`:** Test suite (to be expanded) - ```bash - pip install -r requirements.txt - ``` +## Key Features to Understand - * **Database Setup:** +### AI Integration - ```bash - # Assuming PostgreSQL is running locally or via Docker - # Create database and apply migrations - # [Specific commands for DB setup, e.g., `alembic upgrade head`] - ``` +- Multi-provider support with fallback mechanisms +* Context-aware documentation generation +* Intelligent framework detection and content customization - * **Run Backend Server:** +### Template System - ```bash - uvicorn app.main:app --reload - # Access API at http://127.0.0.1:8000 - ``` +- Framework-specific templates (Python/FastAPI, TypeScript/React) +* Multiple variants per document type +* Custom template support via configuration -3. **Frontend Setup (TypeScript/React/Next.js Example):** - * **Install Node.js Dependencies:** +### Cursor IDE Integration - ```bash - npm install # or yarn install - ``` +- Slash commands for in-IDE documentation workflow +* Zero-installation setup through Cursor rules +* Seamless integration with existing project workflows - * **Run Frontend Dev Server:** +### Diagram Generation - ```bash - npm run dev # or yarn dev - # Access frontend at http://localhost:3000 - ``` +- Mermaid-based diagrams stored as version-controlled text +* ER diagrams from SQLAlchemy model analysis +* Architecture diagrams from project structure analysis -4. **Configuration:** - * Copy `.env.example` to `.env` and fill in necessary environment variables: +## Development Workflow - ```bash - cp .env.example .env - # Edit .env with your local settings - ``` +1. **Create Feature Branch:** `git checkout -b feature/your-feature-name` +2. **Make Changes:** Follow coding standards and write tests +3. **Test Thoroughly:** Test both CLI and Cursor IDE integration +4. **Update Documentation:** Update relevant docs if needed +5. **Submit PR:** Create pull request with clear description +6. **Address Review:** Respond to code review feedback +7. **Merge:** Maintainer will merge approved changes -## Project Structure Overview +## Testing Guidelines -* **`/backend`:** Contains the Python FastAPI application. - * `/backend/app/api`: API route definitions. - * `/backend/app/models`: Database models (SQLAlchemy). - * `/backend/app/services`: Business logic. -* **`/frontend`:** Contains the Next.js/React frontend application. - * `/frontend/pages`: Next.js pages/routes. - * `/frontend/components`: Reusable React components. - * `/frontend/lib`: Utility functions and client-side logic. -* **`/docs`:** Project documentation, including ADRs and architecture overview. -* **`/tests`:** Unit and integration tests for both backend and frontend. +* **Unit Tests:** Test individual functions and classes +* **Integration Tests:** Test AI provider integrations (with mocking) +* **End-to-End Tests:** Test complete workflows (CLI commands, slash commands) +* **Documentation Tests:** Verify generated documentation is valid ## Resources and Links -* **Jira/Task Tracker:** [Link to Jira, Asana, Trello, etc.] -* **Figma/Design Prototypes:** [Link to Figma, Sketch, Adobe XD, etc.] -* **API Documentation:** [Link to OpenAPI/Swagger UI, Postman collection, etc.] -* **ADR Log:** [Link to docs/adr directory index] -* **Architecture Overview:** [Link to docs/architecture.md] -* **Deployment Dashboard:** [Link to Vercel, Netlify, AWS Console, etc.] +* **GitHub Repository:** [https://github.com/mgiovani/ai-cursor-init](https://github.com/mgiovani/ai-cursor-init) +* **PyPI Package:** [https://pypi.org/project/ai-cursor-init/](https://pypi.org/project/ai-cursor-init/) +* **Architecture Overview:** [docs/architecture.md](./architecture.md) +* **ADR Log:** [docs/adr/](./adr/) +* **Development Patterns:** [docs/development/](./development/) +* **Issue Templates:** [GitHub Issues](https://github.com/mgiovani/ai-cursor-init/issues) + +## Contributing + +We welcome contributions! Please: + +1. **Read the Code:** Understand the existing patterns and architecture +2. **Start Small:** Begin with bug fixes or small feature additions +3. **Ask Questions:** Use GitHub Issues for clarification +4. **Follow Standards:** Maintain code quality and test coverage +5. **Document Changes:** Update relevant documentation --- + +*This onboarding guide is maintained using the ai-cursor-init framework itself - a living example of the tool in action.* diff --git a/images/data-model-generation.png b/images/data-model-generation.png new file mode 100644 index 0000000..9ca7422 Binary files /dev/null and b/images/data-model-generation.png differ diff --git a/images/onboarding-doc-example-2.png b/images/onboarding-doc-example-2.png new file mode 100644 index 0000000..03a7506 Binary files /dev/null and b/images/onboarding-doc-example-2.png differ diff --git a/images/onboarding-doc-example.png b/images/onboarding-doc-example.png new file mode 100644 index 0000000..40c8240 Binary files /dev/null and b/images/onboarding-doc-example.png differ diff --git a/images/system-architecture-example.png b/images/system-architecture-example.png new file mode 100644 index 0000000..6e96fc4 Binary files /dev/null and b/images/system-architecture-example.png differ diff --git a/pr_description.txt b/pr_description.txt deleted file mode 100644 index 5616930..0000000 --- a/pr_description.txt +++ /dev/null @@ -1,32 +0,0 @@ -## ๐Ÿ“ฆ PyPI Publishing Setup - -This PR adds comprehensive PyPI publishing capabilities to the ai-cursor-init framework. - -### โœจ Key Changes - -- **Package Configuration**: Updated `pyproject.toml` with proper metadata for PyPI -- **Package Name**: Changed to `ai-cursor-init` (already published and available) -- **GitHub Actions**: Automated publishing workflow on releases -- **CLI Command**: Available as `ai-cursor-init` after installation -- **Dependencies**: Added `build` and `twine` to dev dependencies -- **Documentation**: Updated README with new package name - -### ๐Ÿš€ Installation - -The package is live on PyPI: - -```bash -pip install ai-cursor-init -ai-cursor-init --help -``` - -### ๐Ÿ”— PyPI Package - -https://pypi.org/project/ai-cursor-init/0.1.0/ - -### ๐Ÿงช Testing - -- โœ… Package builds successfully -- โœ… CLI works correctly after installation -- โœ… Published and verified on PyPI -- โœ… GitHub Actions workflow configured \ No newline at end of file