Phonebook — Cross-Platform Contact Manager

Phonebook is a full-stack, cross-platform personal contact management application. Built with a single Flutter codebase for Web (PWA), iOS, and Android, it connects seamlessly to a Django REST Framework backend powered by JWT authentication.

---

🎯 Project Goal

The primary objective of Phonebook is to provide a unified, secure contact registry that works across mobile and web platforms without codebase fragmentation. It demonstrates clean multi-platform architecture, data isolation per user, and progressive web application (PWA) installation capabilities.

---

✨ Core Features

• 🔐 User Authentication: Secure login and token-based session handling via JWT (SimpleJWT).
• 📇 Contact CRUD Operations: Add, view, edit, and delete contacts (Name, Phone Number, Email, Address).
• 🔒 Data Isolation: Contacts are strictly scoped to the authenticated user via backend queryset filters.
• 🌐 PWA Support:** Installable directly on desktop and mobile browsers via standard Service Worker and Manifest configurations.
• 🔌 Adaptive API Resolver: Dynamic base URL selection (10.0.2.2 for Android Emulators, **127**.0.0.1 / domain for iOS and Web).
• ⚡ Multi-Platform UI: Native operational feel across Android, iOS, and Web from a single Flutter project.

---

🏗️ System Architecture

┌──────────────────────────────────────────────────────────────────┐
│                     **FLUTTER** **FRONTEND** **CLIENT**                      │
│    Android App   │   iOS App   │   Web **PWA** (Desktop/Mobile)      │
└────────────────────────────────┬─────────────────────────────────┘
    │ **HTTPS** / **REST** **API** (**JWT** Bearer Auth)
    ▼
┌──────────────────────────────────────────────────────────────────┐
│                      **DJANGO** **REST** **BACKEND** **API**                     │
│    ┌───────────────────────────┐   ┌────────────────────────┐    │
│    │ SimpleJWT Token Endpoint  │   │ ContactViewSet (**CRUD**)  │    │
│    └───────────────────────────┘   └────────────────────────┘    │
└────────────────────────────────┬─────────────────────────────────┘
    │ Django **ORM**
    ▼
┌──────────────────────────────────────────────────────────────────┐
│                   **DATABASE** (SQLite / PostgreSQL)                 │
└──────────────────────────────────────────────────────────────────┘

---

🛠️ Tech Stack

Layer	Technology	Key Libraries / Modules
Backend	Python / Django	djangorestframework, djangorestframework-simplejwt, django-cors-headers
Frontend	Flutter / Dart	dio (HTTP client), flutter_secure_storage
PWA	Web Manifest & Service Workers	Flutter Web Engine
Database	SQLite (Dev) / PostgreSQL (Prod)	Django ORM

---

📂 Repository Structure

phonebook/
├── backend/                       # Django **REST** Framework backend
│   ├── contacts/                  # App housing models, views, and serializers
│   │   ├── models.py              # Contact data definition
│   │   ├── views.py               # ContactViewSet with user isolation
│   │   └── serializers.py        # Serializer definitions
│   ├── phonebook_backend/         # Project config, settings, and URLs
│   ├── manage.py
│   └── requirements.txt
└── frontend/                      # Flutter multi-platform application
    ├── lib/
    │   ├── main.dart              # Application entrypoint
    │   └── services/              # ApiClient & Auth state logic
    ├── web/                       # Web & **PWA** assets
    │   ├── index.html
    │   └── manifest.json          # **PWA** configuration
    └── pubspec.yaml

---

🔌 API Endpoints

All contact endpoints require a valid Authorization: Bearer <access_token> header.

Method	Endpoint	Description	Auth Required
POST	/api/auth/token/	Obtain JWT access and refresh token pair	No
POST	/api/auth/token/refresh/	Refresh expired JWT access token	No
GET	/api/contacts/	List all contacts owned by current user	Yes
POST	/api/contacts/	Create a new contact	Yes
GET	/api/contacts/{id}/	Retrieve specific contact details	Yes
PUT	/api/contacts/{id}/	Update an existing contact	Yes
DELETE	/api/contacts/{id}/	Delete a contact	Yes

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• Flutter SDK 3.x+
• Git

---

1. Backend Setup (Django)

(https://github.com/your-username/phonebook.git) cd phonebook/backend

# Create and activate virtual environment

python -m venv venv source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies

pip install django djangorestframework djangorestframework-simplejwt django-cors-headers

# Run database migrations

python manage.py migrate

# Create a superuser for login testing

python manage.py createsuperuser

# Start development server

python manage.py runserver 0.0.0.0:**8000**

---

2. Frontend Setup (Flutter)

# Install Flutter dependencies

flutter pub get

# Run on Web (Chrome)

flutter run -d chrome

# Run on Android / iOS Emulator

flutter run

---

🌐 Building & Deploying the PWA

To generate the production-ready Progressive Web Application bundle:

The output will be placed in build/web. You can host this directory using any standard web host (e.g., NGINX, Vercel, Firebase Hosting, Netlify). When opened in Chrome, Edge, or Safari, users can click Install App to add Phonebook directly to their home screen or desktop.