# Django Backend Starter Template

A modern, production-ready, batteries-included Django backend template built for rapid application development.

---

## 🚀 Tech Stack

- **Framework**: Django 5.0+
- **API Engine**: Django REST Framework (DRF)
- **Admin Interface**: [Django Unfold](https://github.com/unfoldadmin/django-unfold) (Tailwind-based modern UI)
- **Database**: PostgreSQL
- **Caching & Broker**: Redis
- **Task Queue**: Celery & Celery Beat
- **API Documentation**: Swagger UI & ReDoc via `drf-yasg`
- **Static Assets**: WhiteNoise
- **Containerization**: Docker & Docker Compose

---

## 🌟 Key Features

1. **Custom User Authentication (`apps/account`)**:
   - Email-based authentication (no cumbersome usernames).
   - Profile management with avatar, phone number, and metadata.
   - Built-in `LoginHistory` and `LocationHistory` tracking.
   - Standard authentication endpoints (Register, Login, Token Exchange, Password Reset, Profile Update).
   - Clean group and role-based permissions.
2. **Modern Admin Panel (`utils/admin.py` & Django Unfold)**:
   - Modern Tailwind styling with dark/light mode.
   - Dynamic Dashboard KPI statistics.
   - Responsive sidebar with configurable navigation.
3. **Interactive API Documentation (`apps/api`)**:
   - Live Swagger UI at `/swagger/` and ReDoc at `/redoc/`.
   - Token authentication banner for test requests.
   - Health check endpoint at `/api/v1/health/`.
   - Mobile app release versioning (`AppVersion`).
4. **Runtime Dynamic Preferences (`dynamic_preferences/`)**:
   - Editable site-wide settings directly from the admin panel (site title, contact email, maintenance mode).
5. **Production Ready**:
   - Multi-stage Dockerfile and Docker Compose setup.
   - Nginx reverse proxy configuration.
   - Pre-configured Gzip compression, security headers, and media streaming.

---

## 📁 Project Structure

```text
├── apps/
│   ├── account/              # Custom User, authentication, profile, notifications
│   │   ├── admin/            # Unfold user and group admin
│   │   ├── migrations/       # Initial schema migrations
│   │   ├── models/           # User, LoginHistory, Notification models
│   │   ├── serializers/      # DRF serializers for user & auth
│   │   ├── views/            # Register, login, profile, notification views
│   │   └── urls.py           # Account API endpoints
│   └── api/                  # Core API utilities, versions, health checks
│       ├── admin/            # Version & support admin
│       ├── migrations/       # Initial schema migrations
│       ├── models/           # AppVersion, SupportMessage
│       ├── serializers/      # API serializers
│       ├── views/            # HealthCheck, AppVersion, Swagger views
│       └── urls.py           # Core API routes
├── config/
│   ├── settings/
│   │   ├── base.py           # Base Django settings
│   │   ├── develop.py        # Development settings
│   │   ├── production.py     # Production settings
│   │   └── test.py           # Test settings
│   ├── celery.py             # Celery worker configuration
│   ├── urls.py               # Root URL configuration
│   ├── wsgi.py               # WSGI entry point
│   └── asgi.py               # ASGI entry point
├── dynamic_preferences/       # In-tree runtime preferences registry
├── nginx/
│   └── app.conf              # Nginx reverse proxy config
├── static/                   # Static CSS and JS assets
├── templates/
│   ├── admin/                # Unfold admin dashboard & overrides
│   └── swagger/              # Custom Swagger UI templates
├── utils/                    # Reusable helper modules
│   ├── admin.py              # Unfold AdminSite and dashboard callbacks
│   ├── exceptions.py         # DRF custom exception handler
│   ├── image_compression.py  # Image optimization
│   ├── pagination.py         # Standard REST pagination
│   └── redis.py              # Redis token and cache helpers
├── .env.example              # Environment variables template
├── .env.dev                  # Local development env defaults
├── docker-compose.yml        # Docker compose configuration
├── Dockerfile                # Docker build file
├── manage.py                 # Django CLI
└── requirements.txt          # Python dependencies
```

---

## 🛠️ Quick Start

### 1. Using Docker (Recommended)

1. **Clone or copy the template**:
   ```bash
   git init my-project
   cd my-project
   ```

2. **Setup environment variables**:
   ```bash
   cp .env.example .env.dev
   ```

3. **Build and start services**:
   ```bash
   docker compose up -d --build
   ```

4. **Run migrations and create superuser**:
   ```bash
   docker compose exec web python manage.py migrate
   docker compose exec web python manage.py createsuperuser
   ```

5. Access the app:
   - **Admin Panel**: [http://localhost:8000/admin/](http://localhost:8000/admin/)
   - **Swagger Docs**: [http://localhost:8000/swagger/](http://localhost:8000/swagger/)
   - **Health Check**: [http://localhost:8000/api/v1/health/](http://localhost:8000/api/v1/health/)

---

### 2. Local Python Environment

1. **Create and activate a virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment**:
   ```bash
   cp .env.example .env
   # Edit .env with your local PostgreSQL and Redis credentials
   ```

4. **Apply migrations**:
   ```bash
   python manage.py migrate
   python manage.py createsuperuser
   ```

5. **Run the development server**:
   ```bash
   python manage.py runserver
   ```

---

## 🔑 Environment Variables Reference

| Variable | Description | Default |
|----------|-------------|---------|
| `DJANGO_SECRET_KEY` | Unique Django secret key | (Required in production) |
| `DJANGO_DEBUG` | Enable debug mode | `True` |
| `DJANGO_ALLOWED_HOSTS` | Comma-separated allowed hostnames | `127.0.0.1,localhost` |
| `POSTGRES_DB` | PostgreSQL database name | `app_db` |
| `POSTGRES_USER` | PostgreSQL user | `postgres` |
| `POSTGRES_PASSWORD` | PostgreSQL password | `postgres` |
| `POSTGRES_HOST` | PostgreSQL host | `postgres` / `localhost` |
| `POSTGRES_PORT` | PostgreSQL port | `5432` |
| `REDIS_URL` | Redis connection URL | `redis://redis:6379/0` |
| `SENTRY_DSN` | Sentry error tracking DSN | (Optional) |

---

## 📡 API Endpoints Overview

- **Auth & Account**:
  - `POST /api/v1/account/register/` - User registration
  - `POST /api/v1/account/login/` - User login & token generation
  - `GET /api/v1/account/profile/` - Authenticated user profile
  - `PUT /api/v1/account/profile/update/` - Update profile
  - `POST /api/v1/account/recover/` - Request password recovery
  - `POST /api/v1/account/reset/` - Reset password
- **System & Utilities**:
  - `GET /api/v1/health/` - Server health status
  - `GET /api/v1/version/` - Latest mobile application version
  - `POST /api/v1/contact-us/` - Submit support/contact message
- **Documentation**:
  - `/swagger/` - Interactive Swagger UI
  - `/redoc/` - ReDoc API documentation