Metadata-Version: 2.4
Name: cfs-cli
Version: 0.2.2
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: jinja2
Requires-Dist: pyyaml
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist

# 🚀 CFS - Common Folder Structure Generator

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Framework](https://img.shields.io/badge/frameworks-3-orange.svg)](#supported-frameworks)

> **A powerful, manifest-driven project scaffold generator that creates production-ready applications with consistent, well-organized folder structures.**

CFS automatically generates complete project structures for multiple frameworks, handling everything from initial project setup to dependency installation. Say goodbye to repetitive project configuration and hello to instant, production-ready codebases! ✨

---

## 📑 Table of Contents

- [Features](#-features)
- [Supported Frameworks](#-supported-frameworks)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Framework Guides](#-framework-guides)
  - [Spring Boot](#-spring-boot)
  - [Flutter](#-flutter)
  - [Django](#-django)
- [CLI Reference](#-cli-reference)
- [Project Structure](#-project-structure)
- [Contributing](#-contributing)
- [License](#-license)

---

## ✨ Features

✅ **Multi-Framework Support** - Spring Boot, Flutter, Django (more coming soon!)  
✅ **Manifest-Driven** - Configure your project structure with simple YAML files  
✅ **Production-Ready** - Generated projects follow industry best practices  
✅ **Automated Setup** - From project creation to dependency installation  
✅ **Modular Architecture** - Clean separation of concerns in all templates  
✅ **Customizable** - Flexible variable system for personalized projects  
✅ **Interactive CLI** - User-friendly command-line interface with colored output  
✅ **Dry Run Mode** - Preview changes before generating files  
✅ **Comprehensive Validation** - Strict checks for template files and configurations  

---

## 🎯 Supported Frameworks

| Framework | Status | Backend/Frontend | Database | API Support |
|-----------|--------|------------------|----------|-------------|
| 🍃 **Spring Boot** | ✅ Available | Backend (JVM) | PostgreSQL, MySQL, SQLite | REST, GraphQL, WebSocket |
| 📱 **Flutter** | ✅ Available | Mobile/Web Frontend | N/A | REST, GraphQL, WebSocket |
| 🐍 **Django** | ✅ Available | Backend (Python) | PostgreSQL, MySQL, SQLite | REST, GraphQL |
| ⚛️ React | 🔄 Coming Soon | Frontend | N/A | REST, GraphQL |
| ⚡ Next.js | 🔄 Coming Soon | Full-stack | Any | REST, GraphQL |
| 🔥 FastAPI | 🔄 Coming Soon | Backend (Python) | Any | REST, GraphQL |

---

## 📦 Installation

### Prerequisites

- **Python 3.9+** installed
- **Git** installed
- Framework-specific requirements:
  - **Spring Boot**: Java 11+ and Maven/Gradle
  - **Flutter**: Flutter SDK 3.0+
  - **Django**: Python 3.9+

### Install from Source

```bash
# Clone the repository
git clone https://github.com/yourusername/cfs-generator.git
cd cfs-generator

# Install dependencies
pip install -r requirements.txt

# Install CFS globally
pip install -e .

# Verify installation
cfs --version
```

### Quick Install (Coming Soon)

```bash
pip install cfs-generator
```

---

## 🚀 Quick Start

### Generate Your First Project

```bash
# List available templates
cfs list

# Generate a Spring Boot project
cfs init springboot -p my-api -l java -a rest

# Generate a Flutter app
cfs init flutter -p my_mobile_app -a graphql

# Generate a Django backend
cfs init django -p my_backend --package-name myapp -d postgresql --use-graphql
```

### Interactive Mode

Simply run without options to use interactive prompts:

```bash
cfs init springboot
```

The CLI will guide you through:
- Project name
- Package name
- Language selection
- API protocol
- Database engine (where applicable)
- Additional features

---

## 📚 Framework Guides

---

## 🍃 Spring Boot

Create enterprise-grade Java/Kotlin REST, GraphQL, or WebSocket APIs with Spring Boot.

### Features

✅ **Java 11-21** or **Kotlin** support  
✅ **REST, GraphQL, WebSocket** APIs  
✅ **PostgreSQL, MySQL, SQLite** database support  
✅ **Modular architecture** with controllers, services, repositories  
✅ **JPA/Hibernate** ORM integration  
✅ **Exception handling** and validation  
✅ **Docker** configuration included  

### Usage

```bash
# Basic REST API with Java
cfs init springboot \
  --project-name user-service \
  --package-name com.company.users \
  --language java \
  --api-protocol rest

# GraphQL API with Kotlin
cfs init springboot \
  -p product-api \
  --package-name io.shop.products \
  -l kt \
  -a graphql

# WebSocket server
cfs init springboot \
  -p chat-server \
  --package-name com.chat.server \
  -l java \
  -a websocket
```

### Project Structure

```
my-spring-api/
├── src/
│   ├── main/
│   │   ├── java/com/company/myapi/
│   │   │   ├── controllers/        # REST/GraphQL controllers
│   │   │   ├── models/             # JPA entities
│   │   │   ├── services/           # Business logic
│   │   │   ├── repositories/       # Data access layer
│   │   │   ├── dtos/               # Data transfer objects
│   │   │   ├── exceptions/         # Custom exceptions
│   │   │   └── MyApiApplication.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
├── pom.xml                         # Maven dependencies
├── Dockerfile
└── README.md
```

### What You Get

- ✅ User CRUD operations (Create, Read, Update, Delete)
- ✅ Global exception handler
- ✅ Input validation with DTOs
- ✅ Database configuration (H2 for dev, production DB)
- ✅ Mapper pattern for entity ↔ DTO conversion
- ✅ Service layer with business logic
- ✅ Repository layer with JPA

### Next Steps

```bash
cd my-spring-api
./mvnw spring-boot:run

# API available at: http://localhost:8080
# GraphQL playground: http://localhost:8080/graphql
```

---

## 📱 Flutter

Build beautiful, natively compiled mobile, web, and desktop applications with Flutter.

### Features

✅ **Modular clean architecture** (data/presentation/routes)  
✅ **GraphQL, REST, WebSocket** API clients  
✅ **go_router** for declarative navigation  
✅ **Provider** for state management  
✅ **Authentication & Onboarding** modules included  
✅ **Theming** with dark mode support  
✅ **Custom widgets** library  
✅ **Secure storage** for sensitive data  

### Usage

```bash
# GraphQL mobile app
cfs init flutter \
  --project-name shopping_app \
  --package-name com.mycompany.shopping \
  --api-protocol graphql

# REST API app
cfs init flutter \
  -p weather_app \
  --package-name io.weather.app \
  -a rest

# WebSocket real-time app
cfs init flutter \
  -p chat_app \
  --package-name com.chat.mobile \
  -a websocket
```

### Project Structure

```
my_flutter_app/
├── lib/
│   ├── core/                       # Core infrastructure
│   │   ├── api_config/            # API client setup
│   │   │   └── graphql/           # GraphQL config
│   │   ├── constants/             # App constants
│   │   ├── routes/                # App routing
│   │   ├── storage/               # Secure storage
│   │   └── theme/                 # Material theme
│   ├── modules/                   # Feature modules
│   │   ├── authentication/
│   │   │   ├── data/             # Models, services, GraphQL
│   │   │   ├── presentation/     # Screens, widgets, providers
│   │   │   └── routes/           # Module routing
│   │   └── onboarding/
│   ├── shared/                    # Shared utilities
│   │   └── utilities/
│   │       ├── helper_methods/   # Utility functions
│   │       └── widgets/          # Reusable widgets
│   ├── app.dart                   # App widget
│   └── main.dart                  # Entry point
├── pubspec.yaml                   # Dependencies
├── .env.example
└── docs/
    └── ARCHITECTURE.md
```

### What You Get

**🔐 Authentication Module**
- Login screen
- Password reset
- Change password
- Local & remote data sources
- JWT token management

**🎯 Onboarding Module**
- Splash screen
- Multi-page onboarding flow
- Smooth page indicators
- Skip/Next navigation

**🎨 UI Components**
- Custom buttons, text fields, dropdowns
- Loading indicators
- Date pickers
- Glass morphism containers
- Theme controller (light/dark)

**🔧 Utilities**
- Avatar color generator
- Date formatters
- Device security checker
- Input validators
- Custom clippers & animations

### Packages Included

- `graphql_flutter` - GraphQL client
- `go_router` - Declarative routing
- `provider` - State management
- `flutter_secure_storage` - Secure data storage
- `dio` & `http` - HTTP clients
- `sizer` - Responsive sizing
- `hugeicons` & `heroicons` - Icon libraries
- `smooth_page_indicator` - Page indicators
- `flutter_animate` - Animations
- And many more...

### Next Steps

```bash
cd my_flutter_app
flutter pub get
flutter run

# Configure your GraphQL endpoint in .env
# Edit lib/core/api_config/graphql/graphql_url_config.dart
```

---

## 🐍 Django

Create powerful, scalable Python web applications with Django.

### Features

✅ **Python 3.9-3.12** support  
✅ **PostgreSQL, MySQL, SQLite** databases  
✅ **GraphQL** with Graphene-Django (optional)  
✅ **Celery** for async tasks (optional)  
✅ **Redis** caching and message broker  
✅ **Modular Django apps** architecture  
✅ **JWT authentication**  
✅ **Docker & docker-compose** setup  
✅ **Comprehensive utilities** (caching, rate limiting, validators)  

### Usage

```bash
# Full-featured Django backend
cfs init django \
  --project-name ecommerce_backend \
  --package-name ecommerce \
  --database-engine postgresql \
  --python-version 3.11 \
  --use-graphql \
  --use-celery

# Simple REST API
cfs init django \
  -p blog_api \
  --package-name blog \
  -d sqlite

# Interactive mode
cfs init django
```

### Project Structure

```
my_django_backend/
├── myapp_assets/                  # Static assets & config
│   ├── locations/                # CSV location data
│   ├── countries.json
│   └── permissions.json
├── myapp_auth/                    # Authentication app
│   ├── models.py                 # User models
│   ├── views.py
│   └── migrations/
├── myapp_audit_logs/              # Audit logging
│   ├── models.py
│   ├── schema.py                 # GraphQL schema
│   └── admin.py
├── myapp_backend/                 # Core Django project
│   ├── settings/
│   │   ├── base.py              # Base settings
│   │   ├── development.py       # Dev settings
│   │   └── production.py        # Prod settings
│   ├── urls.py                   # URL routing
│   ├── schema.py                 # GraphQL root schema
│   ├── celery.py                 # Celery config
│   ├── wsgi.py
│   └── asgi.py
├── myapp_cache_core/              # Caching utilities
│   ├── models.py
│   └── management/commands/
├── myapp_notifications/           # Notification system
│   ├── models.py
│   ├── tasks.py                  # Celery tasks
│   ├── schema.py
│   └── signals.py
├── myapp_settings/                # App settings
│   ├── models.py
│   └── management/commands/
│       └── seed_locations.py    # Data seeding
├── myapp_files/                   # File management
├── myapp_dto/                     # Data Transfer Objects
│   ├── auth_dto.py
│   ├── enums.py
│   └── shared_dto.py
├── myapp_dto_builders/            # DTO builders
│   └── response_builder.py
├── myapp_mixins/                  # Reusable mixins
│   ├── base_crud.py
│   └── models.py
├── myapp_utils/                   # Utility modules
│   ├── cache/
│   │   ├── decorators.py
│   │   ├── manager.py
│   │   └── utils.py
│   ├── decorators/
│   │   ├── log_exceptions.py
│   │   ├── permissions.py
│   │   └── scope.py
│   ├── rate_limit/
│   │   ├── decorators.py
│   │   ├── middleware.py
│   │   └── token_bucket.py
│   ├── validators/
│   │   ├── input_validator.py
│   │   └── password_validator.py
│   ├── authentication.py
│   ├── notification_utils.py
│   └── user_utils.py
├── myapp_htmls/                   # Email templates
│   ├── account_activation.html
│   └── password-reset.html
├── logs/                          # Application logs
├── docs/                          # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   └── DEPLOYMENT.md
├── manage.py
├── requirements.txt
├── requirements-dev.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md
```

### What You Get

**🔐 Authentication App**
- Custom user model
- JWT authentication
- Permission system
- User management

**📊 Audit Logs**
- Track all user actions
- GraphQL queries for logs
- Admin interface

**🔔 Notifications**
- Email notifications
- In-app notifications
- Celery async tasks
- Notification templates

**⚙️ Settings App**
- Application settings
- Location data (Countries, Regions, Districts, Wards, Streets)
- Data seeding commands

**📁 File Management**
- File upload/download
- Image processing
- File validation

**🛠️ Utilities**
- **Caching**: Redis-backed caching decorators
- **Rate Limiting**: Token bucket algorithm
- **Decorators**: Permissions, logging, scopes
- **Validators**: Input validation, password strength
- **Authentication**: JWT helpers, token management

### Packages Installed

**Core**
- `django` - Web framework
- `djangorestframework` - REST API
- `django-cors-headers` - CORS support
- `python-decouple` - Environment variables

**Database**
- `psycopg2-binary` - PostgreSQL adapter
- `mysqlclient` - MySQL adapter (if selected)

**GraphQL** (optional)
- `graphene-django` - GraphQL server
- `django-graphql-jwt` - JWT authentication
- `graphene-file-upload` - File uploads

**Celery** (optional)
- `celery` - Task queue
- `redis` - Message broker
- `django-celery-beat` - Periodic tasks
- `django-celery-results` - Task results

**Utilities**
- `requests` - HTTP client
- `PyJWT` - JWT tokens
- `gunicorn` - WSGI server
- `whitenoise` - Static files
- `django-redis` - Redis cache

**Development**
- `black` - Code formatter
- `flake8` - Linter
- `pytest` - Testing
- `pytest-django` - Django testing
- `faker` - Test data

### Next Steps

```bash
cd my_django_backend
source venv/bin/activate

# Configure database in .env
cp .env.example .env
nano .env

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Seed location data
python manage.py seed_locations

# Start development server
python manage.py runserver

# API available at: http://localhost:8000
# GraphQL endpoint: http://localhost:8000/graphql
# Admin panel: http://localhost:8000/admin
```

### Running with Docker

```bash
# Build and run
docker-compose up --build

# Run migrations
docker-compose exec web python manage.py migrate

# Create superuser
docker-compose exec web python manage.py createsuperuser
```

---

## 🎮 CLI Reference

### Global Options

```bash
cfs [COMMAND] [OPTIONS]
```

### Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize a new project |
| `list` | List all available templates |
| `--version` | Show version information |
| `--help` | Show help message |

### Init Options

| Option | Short | Description | Applicable To |
|--------|-------|-------------|---------------|
| `--project-name` | `-p` | Project name | All |
| `--package-name` | | Package/namespace | Spring Boot, Django |
| `--language` | `-l` | Programming language | Spring Boot |
| `--api-protocol` | `-a` | API type (rest/graphql/websocket) | Spring Boot, Flutter |
| `--database-engine` | `-d` | Database (postgresql/mysql/sqlite) | Django |
| `--python-version` | | Python version (3.9-3.12) | Django |
| `--use-graphql` | | Include GraphQL support | Django |
| `--use-celery` | | Include Celery | Django |
| `--output-dir` | `-o` | Output directory | All |
| `--force` | `-f` | Overwrite existing files | All |
| `--dry-run` | | Preview without creating | All |
| `--debug` | | Show debug information | All |

### Examples

```bash
# List available templates
cfs list

# Dry run to preview
cfs init springboot -p test-api --dry-run

# Force overwrite existing project
cfs init flutter -p my_app --force

# Debug mode for troubleshooting
cfs init django -p backend --debug

# Custom output directory
cfs init springboot -p api -o ~/projects

# Interactive mode
cfs init flutter
```

---

## 🏗️ Project Structure

```
cfs-generator/
├── cfs/
│   ├── modules/
│   │   └── templates/
│   │       ├── springboot/
│   │       │   ├── core/
│   │       │   │   ├── spring_generator.py
│   │       │   │   └── spring_manifest_loader.py
│   │       │   ├── scripts/
│   │       │   │   ├── pre_gen.sh
│   │       │   │   └── post_gen.sh
│   │       │   ├── src_templates/
│   │       │   └── manifest.yml
│   │       ├── flutter/
│   │       │   ├── core/
│   │       │   │   ├── flutter_generator.py
│   │       │   │   ├── flutter_manifest_loader.py
│   │       │   │   └── exceptions/
│   │       │   ├── scripts/
│   │       │   ├── src_templates/
│   │       │   └── manifest.yaml
│   │       └── django/
│   │           ├── core/
│   │           │   ├── django_generator.py
│   │           │   ├── django_manifest_loader.py
│   │           │   └── exceptions/
│   │           ├── scripts/
│   │           ├── src_templates/
│   │           └── manifest.yml
│   └── cli.py
├── docs/
├── tests/
├── requirements.txt
├── setup.py
├── README.md
└── LICENSE
```

---

## 🤝 Contributing

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

### Adding a New Framework

1. Create a new directory under `cfs/modules/templates/{framework_name}`
2. Implement the required files:
   - `manifest.yml` - Template configuration
   - `core/{framework}_generator.py` - Generator class
   - `core/{framework}_manifest_loader.py` - Validation class
   - `core/exceptions/` - Custom exceptions
   - `scripts/pre_gen.sh` - Pre-generation setup
   - `scripts/post_gen.sh` - Post-generation setup
   - `src_templates/` - Jinja2 template files

3. Update `cli.py` to include your framework in `get_framework_modules()`

4. Test thoroughly:
   ```bash
   cfs init {framework} -p test_project --dry-run
   cfs init {framework} -p test_project
   ```

5. Submit a pull request!

### Reporting Issues

Found a bug? Have a suggestion? Please open an issue on GitHub with:
- Framework name
- Command used
- Expected vs actual behavior
- Error messages (if any)
- System information (OS, Python version, framework version)

---

## 📄 License

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

---

## 🙏 Acknowledgments

- Inspired by Yeoman, Vue CLI, and Create React App
- Built with love using Python and Click
- Special thanks to all contributors

---

## 📬 Contact

- **Issues**: [GitHub Issues](https://github.com/James-Edward-Ntigwimbugwa/cfs-generator/issues)
- **Discussions**: [GitHub Discussions](https://github.com/James-Edward-Ntigwimbugwa/cfs-generator/discussions)
- **Email**: james.ntigwimbugwa@eganet.go.tz

---

<div align="center">

**Made with ❤️ by developers, for developers**

⭐ Star us on GitHub — it motivates us a lot!

<!-- [Documentation](https://docs.example.com) • [Examples](https://examples.example.com) • [Blog](https://blog.example.com) -->

</div>
