Feat/brand modal

.gitignore

@@ -1,3 +1,15 @@
 BASIC_COMMANDS.md
 /DJANGO_GUIDE
 phase1-api-starter.md
+/pak_wheels/users/__pycache__
+/pak_wheels/users/migrations/__pycache__
+/media/listings
+/pak_wheels/__pycache__
+PHASE1_REVIEW_GUIDE.md
+PHASE1_REVIEW_GUIDE.md
+*.pyc
+*.pyc
+/pak_wheels/__pycache__
+pak_wheels/__pycache__/urls.cpython-314.pyc
+deep_dive_api_dry_run.md
+*.pyc

pak_wheels/cars/admin.py

@@ -0,0 +1,14 @@
+from django.contrib import admin
+from .models import CarBrand, CarModel
+
+@admin.register(CarBrand)
+class CarBrandAdmin(admin.ModelAdmin):
+    list_display = ('name', 'slug', 'created')
+    search_fields = ('name',)
+    prepopulated_fields = {'slug': ('name',)}
+
+@admin.register(CarModel)
+class CarModelAdmin(admin.ModelAdmin):
+    list_display = ('name', 'brand', 'created')
+    list_filter = ('brand',)
+    search_fields = ('name', 'brand__name')

pak_wheels/cars/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class CarsConfig(AppConfig):
+    name = 'pak_wheels.cars'

pak_wheels/cars/management/commands/seed_cars.py

@@ -0,0 +1,46 @@
+from django.core.management.base import BaseCommand
+from pak_wheels.cars.models import CarBrand, CarModel
+
+
+CAR_DATA = {
+    'Toyota': ['Corolla', 'Yaris', 'Vitz', 'Prius', 'Aqua', 'Land Cruiser',
+               'Fortuner', 'Hilux', 'Camry', 'Premio', 'Passo'],
+    'Honda': ['Civic', 'City', 'BR-V', 'HR-V', 'Vezel', 'Accord', 'N-Wgn',
+              'Freed', 'Fit'],
+    'Suzuki': ['Mehran', 'Cultus', 'Wagon R', 'Alto', 'Swift', 'Bolan',
+               'Ravi', 'Ciaz', 'Vitara', 'APV', 'Every'],
+    'Hyundai': ['Tucson', 'Elantra', 'Sonata', 'Santa Fe', 'Porter', 'H-100'],
+    'Kia': ['Sportage', 'Picanto', 'Stonic', 'Sorento', 'Carnival'],
+    'MG': ['HS', 'ZS EV', 'ZS', '5'],
+    'Changan': ['Alsvin', 'Karvaan', 'M9', 'Oshan X7', 'CS35 Plus'],
+    'Proton': ['Saga', 'X70', 'X50'],
+    'Nissan': ['Dayz', 'Moco', 'Clipper', 'Sunny', 'X-Trail'],
+    'Daihatsu': ['Mira', 'Move', 'Cuore', 'Hijet', 'Tanto', 'Copen'],
+    'BMW': ['3 Series', '5 Series', '7 Series', 'X1', 'X3', 'X5'],
+    'Mercedes-Benz': ['C-Class', 'E-Class', 'S-Class', 'GLA', 'GLC', 'GLE'],
+    'Audi': ['A3', 'A4', 'A6', 'Q3', 'Q5', 'Q7'],
+}
+
+
+class Command(BaseCommand):
+    help = 'Seeds the database with car brands and models for Pakistan market'
+
+    def handle(self, *args, **kwargs):
+        self.stdout.write('Seeding car brands and models...')
+
+        for brand_name, models in CAR_DATA.items():
+            brand, created = CarBrand.objects.get_or_create(name=brand_name)
+            if created:
+                self.stdout.write(self.style.SUCCESS(f'Created brand: {brand_name}'))
+
+            for model_name in models:
+                model, created = CarModel.objects.get_or_create(
+                    brand=brand,
+                    name=model_name
+                )
+                if created:
+                    self.stdout.write(f'  + {model_name}')
+
+        self.stdout.write(self.style.SUCCESS('\nDone! Database seeded.'))
+        self.stdout.write(f'Total brands: {CarBrand.objects.count()}')
+        self.stdout.write(f'Total models: {CarModel.objects.count()}')

pak_wheels/cars/migrations/0001_initial.py

@@ -0,0 +1,43 @@
+# Generated by Django 6.0.4 on 2026-05-08 04:41
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CarBrand',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100, unique=True)),
+                ('slug', models.SlugField(blank=True, max_length=100, unique=True)),
+                ('logo', models.ImageField(blank=True, null=True, upload_to='brands/')),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('modified', models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                'ordering': ['name'],
+            },
+        ),
+        migrations.CreateModel(
+            name='CarModel',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100)),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('modified', models.DateTimeField(auto_now=True)),
+                ('brand', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='models', to='cars.carbrand')),
+            ],
+            options={
+                'ordering': ['name'],
+                'unique_together': {('brand', 'name')},
+            },
+        ),
+    ]

pak_wheels/cars/migrations/0002_carbrand_is_active_carmodel_is_active_and_more.py

@@ -0,0 +1,29 @@
+# Generated by Django 6.0.4 on 2026-05-11 09:49
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('cars', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='carbrand',
+            name='is_active',
+            field=models.BooleanField(default=True),
+        ),
+        migrations.AddField(
+            model_name='carmodel',
+            name='is_active',
+            field=models.BooleanField(default=True),
+        ),
+        migrations.AlterField(
+            model_name='carmodel',
+            name='brand',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='models', to='cars.carbrand'),
+        ),
+    ]

pak_wheels/cars/models.py

@@ -0,0 +1,48 @@
+from django.db import models
+from django.utils.text import slugify
+
+
+class CarBrand(models.Model):
+    """e.g. Toyota, Honda, Suzuki"""
+    name = models.CharField(max_length=100, unique=True)
+    slug = models.SlugField(max_length=100, unique=True, blank=True)
+    logo = models.ImageField(upload_to='brands/', blank=True, null=True)
+    is_active = models.BooleanField(default=True)
+
+    created = models.DateTimeField(auto_now_add=True)
+    modified = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ['name']
+
+    def save(self, *args, **kwargs):
+        # Auto-generate slug from name if not provided
+        if not self.slug:
+            self.slug = slugify(self.name)
+        super().save(*args, **kwargs)
+
+    def __str__(self):
+        return self.name
+
+
+class CarModel(models.Model):
+    """e.g. Civic, Corolla, Cultus — belongs to a brand"""
+    brand = models.ForeignKey(
+        CarBrand,
+        on_delete=models.PROTECT,
+        related_name='models'
+    )
+    name = models.CharField(max_length=100)
+    is_active = models.BooleanField(default=True)
+
+    created = models.DateTimeField(auto_now_add=True)
+    modified = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ['name']
+        # Same model name can exist under different brands,
+        # but not twice under the same brand
+        unique_together = [['brand', 'name']]
+
+    def __str__(self):
+        return f"{self.brand.name} {self.name}"

pak_wheels/cars/serializers.py

@@ -0,0 +1,33 @@
+from rest_framework import serializers
+from .models import CarBrand, CarModel
+
+
+class CarModelSerializer(serializers.ModelSerializer):
+    """Model serializer for model list endpoints."""
+    class Meta:
+        model = CarModel
+        fields = ('id', 'name', 'brand', 'is_active')
+
+class CarModelNestedSerializer(serializers.ModelSerializer):
+    """Model serializer for nesting inside a brand (brand is implied)."""
+    class Meta:
+        model = CarModel
+        fields = ('id', 'name', 'is_active')
+
+
+class CarBrandSerializer(serializers.ModelSerializer):
+    """Brand list view — no nested models (lightweight)."""
+    models_count = serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = CarBrand
+        fields = ('id', 'name', 'slug', 'logo', 'models_count', 'is_active')
+
+
+class CarBrandDetailSerializer(serializers.ModelSerializer):
+    """Brand detail view — includes all models (for dropdown)."""
+    models = CarModelNestedSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = CarBrand
+        fields = ('id', 'name', 'slug', 'logo', 'models')

pak_wheels/cars/tests.py

@@ -0,0 +1,3 @@
+from django.test import TestCase
+
+# Create your tests here.

pak_wheels/cars/urls.py

@@ -0,0 +1,12 @@
+from django.urls import path
+from .views import (
+    CarBrandListView,
+    CarBrandDetailView,
+    CarModelListView,
+)
+
+urlpatterns = [
+    path('brands/', CarBrandListView.as_view(), name='brand-list'),
+    path('brands/<int:pk>/', CarBrandDetailView.as_view(), name='brand-detail'),
+    path('models/', CarModelListView.as_view(), name='model-list'),
+]

pak_wheels/cars/views.py

@@ -0,0 +1,51 @@
+from rest_framework import generics, permissions
+from rest_framework.exceptions import ValidationError
+from django.db.models import Count
+from .models import CarBrand, CarModel
+from .serializers import (
+    CarBrandSerializer,
+    CarBrandDetailSerializer,
+    CarModelSerializer,
+)
+
+
+class CarBrandListView(generics.ListAPIView):
+    """
+    GET /api/cars/brands/
+    List all brands (public).
+    """
+    def get_queryset(self):
+        return CarBrand.objects.annotate(models_count=Count('models'))
+    serializer_class = CarBrandSerializer
+    permission_classes = [permissions.AllowAny]
+
+
+class CarBrandDetailView(generics.RetrieveAPIView):
+    """
+    GET /api/cars/brands/<id>/
+    Get brand details with all its models nested.
+    """
+    def get_queryset(self):
+        return CarBrand.objects.prefetch_related('models')
+    serializer_class = CarBrandDetailSerializer
+    permission_classes = [permissions.AllowAny]
+
+
+class CarModelListView(generics.ListAPIView):
+    """
+    GET /api/cars/models/?brand=<brand_id>
+    List all models, optionally filtered by brand.
+    This is what powers cascading dropdowns!
+    """
+    serializer_class = CarModelSerializer
+    permission_classes = [permissions.AllowAny]
+
+    def get_queryset(self):
+        queryset = CarModel.objects.select_related('brand').order_by('name')
+        brand_id = self.request.query_params.get('brand')
+        if brand_id:
+            try:
+                queryset = queryset.filter(brand_id=int(brand_id))
+            except ValueError:
+                raise ValidationError({'brand': 'Invalid brand ID'})
+        return queryset

pak_wheels/listings/admin.py

@@ -0,0 +1,17 @@
+from django.contrib import admin
+from .models import CarListing, CarImage
+
+class CarImageInline(admin.TabularInline):
+    model = CarImage
+    extra = 1
+
+@admin.register(CarListing)
+class CarListingAdmin(admin.ModelAdmin):
+    list_display = ('title', 'seller', 'brand', 'model', 'year', 'price', 'city', 'created')
+    list_filter = ('brand', 'model', 'city', 'created')
+    search_fields = ('title', 'description', 'city', 'seller__full_name')
+    inlines = [CarImageInline]
+
+@admin.register(CarImage)
+class CarImageAdmin(admin.ModelAdmin):
+    list_display = ('listing', 'image', 'is_primary', 'created')

pak_wheels/listings/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class ListingsConfig(AppConfig):
+    name = 'pak_wheels.listings'

pak_wheels/listings/migrations/0001_initial.py

@@ -0,0 +1,48 @@
+# Generated by Django 6.0.4 on 2026-05-07 13:01
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CarListing',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=255)),
+                ('brand', models.CharField(max_length=100)),
+                ('model', models.CharField(max_length=100)),
+                ('year', models.PositiveIntegerField()),
+                ('price', models.DecimalField(decimal_places=2, max_digits=12)),
+                ('city', models.CharField(max_length=100)),
+                ('description', models.TextField(blank=True)),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('modified', models.DateTimeField(auto_now=True)),
+                ('seller', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='listings', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Listing',
+                'verbose_name_plural': 'Listings',
+                'ordering': ['-created'],
+            },
+        ),
+        migrations.CreateModel(
+            name='CarImage',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('image', models.ImageField(upload_to='listings/')),
+                ('is_primary', models.BooleanField(default=False)),
+                ('created', models.DateTimeField(auto_now_add=True)),
+                ('listing', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='images', to='listings.carlisting')),
+            ],
+        ),
+    ]