Metadata-Version: 2.4
Name: jlframework
Version: 1.0.0
Summary: A complete Python framework for full-stack development
Home-page: https://github.com/jlframework/jlframework
Author: JL Framework Team
Author-email: JL Framework Team <contact@jlframework.dev>
License: MIT
Project-URL: Homepage, https://github.com/jlframework/jlframework
Project-URL: Documentation, https://jlframework.readthedocs.io
Project-URL: Repository, https://github.com/jlframework/jlframework
Project-URL: Issues, https://github.com/jlframework/jlframework/issues
Keywords: fastapi,vue,framework,boilerplate,cli,scaffolding
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: pymongo>=4.0.0
Requires-Dist: pyodbc>=5.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# JLFramework

[![PyPI version](https://badge.fury.io/py/jlframework.svg)](https://badge.fury.io/py/jlframework)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A complete Python framework for full-stack development with FastAPI and Vue.js. Create production-ready applications in minutes with Django-like scaffolding and importable utilities.

## ✨ Features

- 🚀 **Rapid Scaffolding** - Create full-stack projects in under 5 minutes
- 🏗️ **Production-Ready Templates** - FastAPI backend + Vue.js frontends with best practices
- 🔧 **Flexible & Modular** - Use only what you need, mix and match templates
- 📦 **Batteries Included** - Database, auth, logging, middleware, and more
- 🐍 **Django-like Experience** - Clean imports and intuitive CLI commands
- 🎨 **Multiple Frontend Options** - Embedded, features, and marketplace templates
- 🔒 **Security First** - Tenant isolation, OIDC auth, audit logging built-in
- 🐳 **Docker Ready** - Dockerfiles included for all templates

## 📦 Installation

```bash
pip install jlframework
```

## 🚀 Quick Start

### Create a New Project

```bash
# Initialize a new project
jlframework init my-awesome-app
cd my-awesome-app

# Add backend
jlframework add backend

# Add frontend
jlframework add frontend-embedded

# List available templates
jlframework list
```

### Use Importable Utilities

```python
from fastapi import FastAPI, Request, Depends
from sqlalchemy.orm import Session
from jlframework import (
    get_db,
    CommonManager,
    AuditManager,
    AuditStatus,
    AuditAction,
    EntityType,
    restrict_access_middleware,
)

app = FastAPI()

# Add middleware
app.middleware("http")(restrict_access_middleware)

@app.get("/api/v1/items")
async def get_items(
    request: Request,
    db: Session = Depends(get_db)
):
    # Get tenant ID from request
    tenant_id = CommonManager.get_tenant_id(request)
    
    # Query database
    items = db.query(Item).filter_by(tenant_id=tenant_id).all()
    
    return {"items": items}
```

## 📚 Available Templates

### Backend
FastAPI backend with:
- Domain-driven design structure
- SQLAlchemy ORM with multiple database support
- Tenant-based access control middleware
- Audit logging with MongoDB
- Azure integration (optional)
- Docker support
- Environment-based configuration

### Frontend - Embedded
Vue.js 3 embedded application with:
- Vite build system
- TypeScript support
- Vue Router
- OIDC authentication (optional)
- API service layer
- Tailwind CSS
- Docker + Nginx deployment

### Frontend - Features
Vue.js 3 micro-frontend features:
- Modular component architecture
- Custom event system
- Shared state management
- Independent deployment

### Frontend - Marketplace
Vue.js 3 marketplace application:
- Full marketplace UI
- Product catalog
- User management
- OIDC authentication

## 🎯 CLI Commands

### `jlframework init`
Initialize a new project with configuration files.

```bash
jlframework init my-project
jlframework init my-project --no-git  # Skip git initialization
```

### `jlframework add`
Add a template to your project.

```bash
jlframework add backend
jlframework add frontend-embedded
jlframework add frontend-features
jlframework add frontend-marketplace
jlframework add backend --skip-install  # Skip dependency installation
```

### `jlframework list`
List all available templates.

```bash
jlframework list
```

## 📖 Importable Utilities

### Database

```python
from jlframework import get_db, get_db_session, database_middleware

# Use as FastAPI dependency
@app.get("/items")
def get_items(db: Session = Depends(get_db)):
    return db.query(Item).all()

# Use as middleware
app.middleware("http")(database_middleware)
```

### Handlers

```python
from jlframework import CommonManager, AuditManager, AuditData

# Get tenant ID from request
tenant_id = CommonManager.get_tenant_id(request)

# Get client information
client_info = CommonManager.get_client_info(request)

# Validate pagination
CommonManager.validate_pagination(page_index=1, page_size=50)

# Audit logging
audit = AuditManager(app_id=1, tenant_id=tenant_id, mongo_connection_string=config)
await audit.save_audit(AuditData(...))
```

### Enums

```python
from jlframework import AuditStatus, AuditAction, EntityType

# Use in your code
status = AuditStatus.SUCCESS
action = AuditAction.CREATE
entity = EntityType.Customer
```

### Middleware

```python
from jlframework import restrict_access_middleware, get_tenant_id

# Add tenant validation middleware
app.middleware("http")(restrict_access_middleware)

# Get tenant ID from request state
tenant_id = get_tenant_id(request)
```

### Configuration

```python
from jlframework import Settings, get_settings

# Get application settings
settings = get_settings()
print(settings.app_name)
print(settings.debug)
```

## 🏗️ Project Structure

After running `jlframework init` and adding templates:

```
my-project/
├── .jlframework.json      # Project configuration
├── README.md              # Project documentation
├── .gitignore            # Git ignore patterns
├── backend/              # FastAPI backend
│   ├── main.py
│   ├── routes.py
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── configs/
│   ├── domains/
│   ├── middlewares/
│   └── shared/
└── frontend/
    ├── embedded/         # Embedded Vue.js app
    ├── features/         # Micro-frontend features
    └── marketplace/      # Marketplace Vue.js app
```

## 🔧 Configuration

### Backend Configuration

The backend template uses environment variables for configuration. Create a `.env` file:

```env
# Application
APP_NAME=My Awesome API
DEBUG=false
HOST=0.0.0.0
PORT=8000

# Database
DATABASE_URL=mssql+pyodbc://user:pass@server/db?driver=ODBC+Driver+17+for+SQL+Server

# Azure (optional)
AZURE_APP_CONFIG_CONNECTION_STRING=...

# MongoDB (for audit logging)
MONGO_CONNECTION_STRING={"connection_string": "...", "database_name": "..."}
```

### Frontend Configuration

Frontend templates use `.env` files for configuration:

```env
VITE_API_URL=http://localhost:8000
VITE_OIDC_AUTHORITY=https://your-oidc-provider
VITE_OIDC_CLIENT_ID=your-client-id
```

## 🐳 Docker Support

All templates include Dockerfiles for containerization:

```bash
# Backend
cd backend
docker build -t my-backend .
docker run -p 8000:8000 my-backend

# Frontend
cd frontend/embedded
docker build -t my-frontend .
docker run -p 80:80 my-frontend
```

## 🧪 Development

### Running Backend

```bash
cd backend
pip install -r requirements.txt
python main.py
```

### Running Frontend

```bash
cd frontend/embedded
npm install
npm run dev
```

## 📝 Examples

### Complete FastAPI Application

```python
from fastapi import FastAPI, Request, Depends
from sqlalchemy.orm import Session
from jlframework import (
    get_db,
    CommonManager,
    restrict_access_middleware,
    database_middleware,
)

app = FastAPI(title="My API")

# Add middlewares
app.middleware("http")(database_middleware)
app.middleware("http")(restrict_access_middleware)

@app.get("/api/v1/customers")
async def get_customers(
    request: Request,
    db: Session = Depends(get_db)
):
    tenant_id = CommonManager.get_tenant_id(request)
    customers = db.query(Customer).filter_by(tenant_id=tenant_id).all()
    return {"customers": customers}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

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

## 🙏 Acknowledgments

- Built with [FastAPI](https://fastapi.tiangolo.com/)
- Frontend powered by [Vue.js](https://vuejs.org/)
- CLI built with [Click](https://click.palletsprojects.com/)
- Templates rendered with [Jinja2](https://jinja.palletsprojects.com/)

## 📞 Support

- 📧 Email: contact@jlframework.dev
- 🐛 Issues: [GitHub Issues](https://github.com/jlframework/jlframework/issues)
- 📖 Documentation: [Read the Docs](https://jlframework.readthedocs.io)

## 🗺️ Roadmap

- [ ] Additional database support (MongoDB, PostgreSQL)
- [ ] More frontend templates (React, Angular)
- [ ] Code generators for models, routes, services
- [ ] Database migration tools
- [ ] Testing utilities
- [ ] Deployment helpers (Kubernetes, Docker Compose)
- [ ] VS Code extension
- [ ] Web-based project configurator

---

Made with ❤️ by the JLFramework Team
