Metadata-Version: 2.4
Name: django-drf-boilerplate
Version: 0.1.1
Summary: Scaffold a production-ready Django REST Framework project in one command — JWT auth, Celery, Channels, audit log, soft delete, and more
License-Expression: MIT
Project-URL: Homepage, https://github.com/Silas003/django-boilerplate
Project-URL: Repository, https://github.com/Silas003/django-boilerplate
Project-URL: Bug Tracker, https://github.com/Silas003/django-boilerplate/issues
Keywords: django,rest-framework,boilerplate,scaffold,cli,jwt,celery,channels,websocket,audit-log
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Environment :: Web Environment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# Django DRF Boilerplate

A CLI tool that scaffolds a production-ready Django REST Framework project in one command. Pick only the features you need — everything else is cleanly removed.

## Install

```bash
pip install django-drf-boilerplate
```

## Quick Start

```bash
boiler new my_project          # interactive feature selection
boiler new my_project --all    # include every feature, no prompts
```

```bash
cd my_project
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
# Edit .env with your settings
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
```

## CLI Commands

| Command | Description |
|---|---|
| `boiler new <name>` | Scaffold a new project (interactive feature selection) |
| `boiler new <name> --all` | Scaffold with all features, no prompts |
| `boiler new <name> -d <dir>` | Scaffold into a specific directory |
| `boiler add app <name>` | Generate a new Django app in an existing project |
| `boiler info` | Show what's included in the boilerplate |
| `boiler doctor` | Check that your environment is ready to run the project |
| `boiler --version` | Print the installed version |

## Optional Features

When running `boiler new`, you are prompted to include or skip each feature:

| Feature | Default | What it adds |
|---|---|---|
| Google OAuth | on | Social login via Google ID token |
| Celery + Redis | on | Async task queue for email delivery |
| Django Channels | on | WebSocket consumer + room pattern |
| Newsletter | on | Subscribe/unsubscribe endpoint |
| Audit log | on | `ActivityLog` model — track who did what and when |

Features you skip are surgically removed: their apps, settings blocks, URL entries, middleware, and requirements lines are all deleted from the scaffolded project.

## What's Always Included

| Feature | Details |
|---|---|
| Auth | JWT access + refresh tokens, OTP email verification, password reset |
| Logout | Refresh token blacklisting via simplejwt |
| Soft delete | `SoftDeleteModel` abstract base in `core/mixins.py` |
| Health check | `GET /health/` — reports DB + Redis status |
| API docs | Swagger UI + ReDoc at `/swagger/` and `/redoc/` |
| Rate limiting | OTP endpoints throttled at 5 requests/hour |
| Pagination | `StandardPagination` (page size 20, max 100) |
| Logging | Console logger, level set via `DJANGO_LOG_LEVEL` env var |

## Apps

| App | Purpose |
|---|---|
| `accounts` | CustomUser, Profile, full auth flow |
| `communications` | WebSocket consumer, Room/Message models, REST endpoints |
| `newsletter` | Subscriber model + Celery email task |
| `activity` | Read-only audit log — management sees all, users see their own |
| `core` | `SoftDeleteModel`, health check, `generate_otp()`, `IsManagement` permission, throttles, pagination |

## API Endpoints

| Method | Endpoint | Description |
|---|---|---|
| GET | `/health/` | Health check — DB + Redis status |
| POST | `/v1/accounts/register/` | Register + sends OTP |
| POST | `/v1/accounts/verify-account/` | Activate account with OTP |
| POST | `/v1/accounts/login/` | Login → JWT tokens |
| POST | `/v1/accounts/logout/` | Blacklist refresh token |
| POST | `/v1/accounts/google/` | Google OAuth login |
| POST | `/v1/accounts/reset-otp/` | Request password reset OTP |
| POST | `/v1/accounts/reset/` | Reset password with OTP |
| POST | `/v1/accounts/resend-otp/` | Resend activation OTP |
| CRUD | `/v1/accounts/profile/` | User profile (scoped to authenticated user) |
| CRUD | `/v1/newsletter/register/` | Subscribe / unsubscribe |
| GET | `/v1/activity/` | Audit log (management: all; user: own) |
| CRUD | `/v1/communications/rooms/` | Chat rooms (management write, authenticated read) |
| WS | `ws/chat_admin/<uuid>/` | WebSocket chat room |

## Environment Variables

`.env` is auto-created from `.env.example` with a freshly generated `SECRET_KEY`:

```
SECRET_KEY=<auto-generated>
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_PORT=587
EMAIL_HOST_USER=
EMAIL_HOST_PASSWORD=
GOOGLE_CLIENT_ID=
CELERY_BROKER_URL=redis://127.0.0.1:6379
CORS_ALLOWED_ORIGINS=http://localhost:3000
CELERY_TASK_ALWAYS_EAGER=False
DJANGO_LOG_LEVEL=INFO
```

## Running Services

```bash
# Terminal 1 — Django dev server
python manage.py runserver

# Terminal 2 — Celery worker (if Celery was included)
celery -A my_project worker --loglevel=info

# Terminal 3 — Redis (if not running as a system service)
redis-server
```

## Using Soft Delete

Any model can opt in to soft deletion by inheriting `SoftDeleteModel`:

```python
from core.mixins import SoftDeleteModel

class Order(SoftDeleteModel):
    ...
```

`Order.objects.all()` excludes soft-deleted rows automatically. Use `Order.all_objects.all()` to include them. Call `instance.delete()` to soft-delete, `instance.restore()` to undo, or `instance.hard_delete()` to permanently remove.

## Using the Audit Log

```python
from activity.models import log_activity

log_activity(request.user, "created_order", target=order, ip_address=request.META.get("REMOTE_ADDR"))
```
