Overview

AirAds is a hyperlocal vendor discovery and advertising platform that helps customers find the right nearby business at the moment they need it — through map, list, augmented-reality and voice-driven search. It serves two sides of a local marketplace: consumers browsing deals, reels and vendor profiles around them, and business owners who claim, run and promote their listings. The product is delivered as seven coordinated sub-apps — a Django REST backend, three React portals (admin, vendor, customer), a planned Flutter mobile client, a shared infrastructure repository and a documentation repository — all developed as proprietary AmalAxis work.

Problem

Local discovery has a cold-start problem: a directory is worthless until it is dense with accurate businesses, yet no owner will hand-enter their listing into an empty platform. AirAds solves this with a claim-to-own model — the catalogue is pre-seeded from Google Places and GeoNames, deduplicated, and then handed to real owners who claim and enrich their entries. Layered on top are harder problems: ranking results by genuine local relevance rather than raw proximity, enforcing strict geographic and role-based access so a city manager only ever touches their own city's data, protecting personally identifiable information end-to-end, and moving vendor video (reels) into object storage without blocking the request path. The system had to reconcile these concerns across a single backend feeding three distinct front-ends and, eventually, a mobile app.

System Design

The backend is a Django 5.1 + Django REST Framework monolith organised into sixteen-plus focused apps — accounts, vendors, discovery, geo, reels, subscriptions, payments, audit, governance, imports, notifications, tags, analytics and the portal-specific vendor_portal/user_portal — exposing roughly 98 endpoints. Authentication uses djangorestframework-simplejwt, with a separate CustomerUserJWTAuthentication class so consumer/vendor tokens are isolated from admin tokens, and JWTs carry geo claims that drive scoping. GeoDjango over PostgreSQL + PostGIS backs spatial queries, with Redis serving as both cache and Celery broker for asynchronous work (notifications, imports, video processing) scheduled via django-celery-beat. PII classified as restricted is encrypted at rest with AES-256-GCM via the cryptography library, masked in display and kept out of logs; drf-spectacular generates the OpenAPI schema and Daphne serves ASGI.

Integrations are deliberate and load-bearing. Stripe (Checkout, customer portal, webhooks) powers the tiered subscription model — Silver, Gold, Diamond and Platinum — whose multipliers feed directly into result ranking. Twilio handles SMS/OTP authentication. Vendor reels and imagery are uploaded to DigitalOcean Spaces (S3-compatible) through django-storages and boto3, using a direct-to-storage pattern that hands the API only an s3_key and duration, with a local MEDIA_ROOT fallback for development. Google Places supplies both the seeding pipeline and per-vendor enrichment, guarded by a documented deduplication strategy.

The three front-ends share a stack — React 18, TypeScript 5, Vite, Zustand for client state and TanStack Query v5 for server state, axios, react-hook-form with Zod validation, Recharts, Lucide icons and a custom "AirAd DLS" design system — but diverge by role. The admin dashboard adds Leaflet maps, CSV import via PapaParse and diff viewing for audited changes; the vendor portal integrates Stripe Elements, Lottie and date pickers for promotions; the customer portal leans on Google Maps, Framer Motion, Swiper and a TikTok-style reels feed. The planned Flutter mobile app (Riverpod, Go Router, Dio, on-device AR and speech_to_text, FCM push) reuses the same API contract. Everything is containerised with Docker Compose behind an Nginx reverse proxy, shipped to DigitalOcean App Platform across development, staging and production, with GitLab CI/CD running lint, Semgrep, TruffleHog secret scanning and tests, plus scripted backups and disaster recovery.