cfs-cli 0.2.2

No project description provided

🚀 CFS - Common Folder Structure Generator

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
• Supported Frameworks
• Installation
• Quick Start
• Framework Guides
  • Spring Boot
  • Flutter
  • Django
• CLI Reference
• Project Structure
• Contributing
• 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

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

pip install cfs-generator

---

🚀 Quick Start

Generate Your First Project

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

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

# 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

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

# 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

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

# 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

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

# 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

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

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

   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 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
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Made with ❤️ by developers, for developers

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