<div align="center">

# Prozes

**Professional Python Project Generator**

A powerful CLI tool for scaffolding production-ready Python applications.
Stop wasting time on boilerplate. Start building features from day one.

[![Tests](https://github.com/jaopdc11/prozes/actions/workflows/test.yml/badge.svg)](https://github.com/jaopdc11/prozes/actions/workflows/test.yml)
[![Lint](https://github.com/jaopdc11/prozes/actions/workflows/lint.yml/badge.svg)](https://github.com/jaopdc11/prozes/actions/workflows/lint.yml)
[![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/)
[![PyPI version](https://badge.fury.io/py/prozes.svg)](https://badge.fury.io/py/prozes)

[Installation](#installation) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Examples](#examples) • [Contributing](#contributing)

</div>

---

## Overview

**Prozes** is a command-line project generator that creates production-ready Python applications with enterprise-grade architectures. Whether you're building a web application, REST API, CLI tool, or following Clean Architecture principles, Prozes provides the scaffolding you need to start coding immediately.

**Type**: CLI Tool / Project Generator (not a framework or library)
**Usage**: Run `prozes` commands to generate project structures - no imports needed

### Why Prozes?

- **Battle-Tested Architectures**: MVC, REST API, CLI, and Clean Architecture patterns
- **Framework Agnostic**: Works with Flask, FastAPI, and more
- **Production-Ready**: Includes logging, environment variables, real tests, and CI/CD
- **Zero Configuration**: Sensible defaults that work out of the box
- **Best Practices Included**: Testing setup, linting, Git integration, and virtual environments
- **Bilingual Support**: Full internationalization (English and Portuguese)
- **Beautiful CLI**: Rich terminal output with progress indicators and helpful messages

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Key Features](#key-features)
- [Architecture Types](#architecture-types)
- [Usage](#usage)
- [Examples](#examples)
- [Configuration](#configuration)
- [Development](#development)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

## Installation

### Via pip (Recommended)

```bash
pip install prozes
```

### From Source

```bash
git clone https://github.com/jaopdc11/prozes.git
cd prozes
pip install -e .
```

### Verify Installation

```bash
prozes --version
prozes --help
```

---

## Quick Start

Get up and running in 30 seconds:

```bash
# Create a FastAPI REST API with all bells and whistles
prozes api my_api --type fastapi --venv --git --install-deps

cd my_api
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn main:app --reload
```

That's it! Your API is running at `http://localhost:8000` with auto-generated docs at `/docs`.

### Other Quick Examples

```bash
# MVC web application with Flask
prozes mvc blog --venv --git

# CLI tool ready for distribution
prozes cli mytool --venv --git

# Clean Architecture project
prozes clean backend --type fastapi --venv --git
```

---

## Key Features

<table>
<tr>
<td width="50%">

**🏗️ Multiple Architectures**
- MVC (Model-View-Controller)
- REST API
- CLI Applications
- Clean Architecture

**⚡ Framework Support**
- Flask
- FastAPI
- Click (for CLI)

**🔧 Development Tools**
- Automatic virtual environment creation
- Git initialization
- Dependency installation
- Testing scaffolding

</td>
<td width="50%">

**🌍 Internationalization**
- English (default)
- Portuguese (pt)
- Easily extensible

**📦 Production Ready**
- Environment variables (`.env.example`)
- Logging configuration
- Real test cases (not placeholders)
- Separate dev dependencies
- CI/CD with GitHub Actions
- Configuration management

**🎨 Developer Experience**
- Beautiful CLI with Rich library
- Progress indicators
- Colored output
- Verbose mode for debugging

</td>
</tr>
</table>

---

## Architecture Types

### 🌐 MVC (Model-View-Controller)

Perfect for web applications with server-side rendering.

```bash
prozes mvc my_webapp --type web-flask --venv --git
```

**Includes:**
- Separate concerns: Models, Views, Controllers
- Template engine setup
- Static files organization
- Configuration management

**Use cases:** Traditional web apps, admin panels, dashboards

---

### 🔌 REST API

Lean and focused API without frontend bloat.

```bash
prozes api my_api --type fastapi --venv --git
```

**Includes:**
- RESTful route structure
- Data models and schemas
- Request/response handling
- Auto-generated API documentation (FastAPI)

**Use cases:** Backend services, mobile app APIs, microservices

---

### 💻 CLI Application

Command-line tools using Click framework.

```bash
prozes cli my_tool --venv --git
```

**Includes:**
- Command structure
- Argument parsing
- Configuration handling
- Distribution setup (setup.py)

**Use cases:** DevOps tools, automation scripts, data processing

---

### 🏛️ Clean Architecture

Enterprise-grade architecture with clear separation of concerns.

```bash
prozes clean my_project --type fastapi --venv --git
```

**Includes:**
- Entities (Domain layer)
- Use Cases (Business logic)
- Adapters (Interfaces)
- Frameworks (External dependencies)

**Use cases:** Large applications, microservices, long-term projects

---

## Usage

### Command Syntax

```bash
prozes <architecture> <project_name> [options]
```

### Common Options

All commands support these options:

| Option | Description | Default |
|--------|-------------|---------|
| `--venv` | Create virtual environment | `false` |
| `--git` | Initialize Git repository | `false` |
| `--python-version` | Python version for venv | System default |
| `--install-deps` | Install dependencies | `false` |
| `-v, --verbose` | Verbose output | `false` |
| `-L, --lang` | Language (`en` or `pt`) | `en` |

### Architecture-Specific Options

#### MVC & API Commands

```bash
-t, --type   Framework type (web-flask, web-fastapi, flask, fastapi)
```

#### Configuration Command

```bash
prozes config --lang pt           # Set default language
prozes config --show              # Show current configuration
```

### Generated Project Structure

#### MVC Project
```
my_webapp/
├── .github/
│   └── workflows/       # CI/CD pipelines
├── app/
│   ├── controllers/     # Request handlers
│   ├── models/          # Data models
│   ├── views/           # View logic
│   ├── templates/       # HTML templates
│   └── static/          # CSS, JS, images
├── config/
│   ├── __init__.py      # Configuration
│   └── logging.py       # Logging setup
├── tests/               # Test suite with real tests
├── main.py              # Entry point
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
├── pyproject.toml       # Pytest configuration
├── .env.example         # Environment variables template
└── .gitignore          # Git ignore rules
```

#### API Project
```
my_api/
├── .github/workflows/   # CI/CD pipelines
├── app/
│   ├── models/          # Data models
│   └── routes/          # API endpoints
├── config/
│   ├── __init__.py      # Configuration
│   └── logging.py       # Logging setup
├── tests/               # Test suite with real API tests
├── main.py              # Entry point
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
├── pyproject.toml       # Pytest configuration
└── .env.example         # Environment variables template
```

#### CLI Project
```
my_tool/
├── .github/workflows/   # CI/CD pipelines
├── my_tool/
│   ├── commands/        # CLI commands
│   └── main.py          # Entry point
├── tests/               # Test suite with Click runner tests
├── setup.py             # Distribution setup
├── pyproject.toml       # Project metadata + pytest config
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
└── .env.example         # Environment variables template
```

#### Clean Architecture Project
```
my_project/
├── .github/workflows/   # CI/CD pipelines
├── src/
│   ├── entities/        # Domain entities
│   ├── use_cases/       # Business logic
│   ├── adapters/        # Interfaces & repositories
│   └── frameworks/      # External dependencies
├── config/
│   ├── __init__.py      # Configuration
│   └── logging.py       # Logging setup
├── tests/
│   ├── unit/            # Unit tests for use cases
│   └── integration/     # Integration tests
├── main.py              # Entry point
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
├── pyproject.toml       # Pytest configuration
└── .env.example         # Environment variables template
```

---

## Examples

### 1. Blog Application (MVC + Flask)

Build a full-featured blog with Flask:

```bash
# Generate the project
prozes mvc blog --type web-flask --venv --git --install-deps -v

# Start development
cd blog
source venv/bin/activate  # Windows: venv\Scripts\activate
python main.py

# Visit http://localhost:5000
```

**What you get:**
- MVC structure with controllers, models, and views
- Template system ready
- Static files organized
- Development server configured
- Real tests for routes and application
- Logging configured
- CI/CD pipeline ready

---

### 2. User Management API (FastAPI)

Create a modern API with auto-generated documentation:

```bash
# Generate the project
prozes api user_service --type fastapi --venv --git --install-deps

# Start the server
cd user_service
source venv/bin/activate
uvicorn main:app --reload

# Interactive docs at http://localhost:8000/docs
```

**What you get:**
- RESTful endpoints structure
- Pydantic models for validation (FastAPI) or Flask blueprints
- Automatic OpenAPI documentation (FastAPI)
- Real API tests with test client
- Health check endpoint
- Logging configured
- CI/CD pipeline ready

---

### 3. DevOps CLI Tool

Build a distributable command-line tool:

```bash
# Generate the project
prozes cli devops-tools --venv --git --install-deps

# Install in development mode
cd devops-tools
pip install -e .

# Use your CLI
devops-tools --help
devops-tools deploy --env production
```

**What you get:**
- Click framework integrated
- Command structure ready
- Configuration management
- Package ready for PyPI
- Tests with Click runner
- CI/CD pipeline ready

---

### 4. Microservice (Clean Architecture + FastAPI)

Enterprise-grade microservice with Clean Architecture:

```bash
# Generate the project
prozes clean payment-service --type fastapi --venv --git --install-deps

# Run tests
cd payment-service
pytest tests/ -v

# Start the service
uvicorn main:app --reload
```

**What you get:**
- Separated layers (entities, use cases, adapters, frameworks)
- Dependency injection examples
- Testability built-in (unit + integration tests)
- Dependency inversion principle applied
- Repository pattern implemented
- Ready for complex business logic

---

## Configuration

### Global Configuration

Set your preferences globally:

```bash
# Set default language to Portuguese
prozes config --lang pt

# View current configuration
prozes config --show
```

### Per-Project Configuration

Each generated project includes:
- `config/` directory for environment-specific settings
- `.env.example` for environment variables (where applicable)
- `requirements.txt` with pinned dependencies

---

## Documentation

- **Full Documentation**: [Coming Soon]
- **API Reference**: [Coming Soon]
- **Tutorials**: [Coming Soon]
- **Examples Gallery**: [Coming Soon]

For now, use `prozes --help` and `prozes <command> --help` for detailed command information.

---

## Roadmap

We have ambitious plans for Prozes. Check out our [ROADMAP.md](ROADMAP.md) to see what's coming:

- 🔌 Plugin system for custom templates
- 🐳 Docker integration
- 🗄️ Database templates (PostgreSQL, MongoDB, etc.)
- 🔐 Authentication scaffolding
- 🌐 More frameworks (Django, Tornado, Sanic)
- 🏗️ More architectures (Hexagonal, CQRS, Event-Driven)

[View Full Roadmap →](ROADMAP.md)

---

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/jaopdc11/prozes.git
cd prozes

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Run Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=prozes --cov-report=html

# Run specific test file
pytest tests/test_core.py -v
```

### Code Quality

```bash
# Format code
black prozes tests

# Lint code
ruff check prozes tests

# Type checking
mypy prozes

# Run all checks (what CI runs)
pre-commit run --all-files
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## Contributing

We welcome contributions! Here's how you can help:

- 🐛 **Report bugs** via [GitHub Issues](https://github.com/jaopdc11/prozes/issues)
- 💡 **Suggest features** through [GitHub Discussions](https://github.com/jaopdc11/prozes/discussions)
- 📝 **Improve documentation**
- 🔧 **Submit pull requests**

Please read our [Contributing Guide](CONTRIBUTING.md) before submitting PRs.

### Contributors

Thanks to all our contributors!

<!-- ALL-CONTRIBUTORS-LIST:START -->
<!-- This section will be automatically generated -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

---

## Community

- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/jaopdc11/prozes/discussions)
- **Issues**: [Report bugs](https://github.com/jaopdc11/prozes/issues)
- **Discord**: [Coming Soon]
- **Twitter**: [Coming Soon]

---

## License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## Acknowledgments

Built with:
- [Click](https://click.palletsprojects.com/) - Command line interface
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output
- [Flask](https://flask.palletsprojects.com/) & [FastAPI](https://fastapi.tiangolo.com/) - Web frameworks

Inspired by:
- [Cookiecutter](https://github.com/cookiecutter/cookiecutter)
- [Vue CLI](https://cli.vuejs.org/)
- [Create React App](https://create-react-app.dev/)

---

<div align="center">

**[⬆ Back to Top](#prozes)**

Made with ❤️ by [jaopdc11](https://github.com/jaopdc11) & [mednick-sys](https://github.com/mednick-sys)

If you find this project useful, please consider giving it a ⭐️

</div>
