Academics App

The Academics App is a full-stack application built with Django (backend) and Next.js (frontend) to manage academic departments within a university system. It provides CRUD (Create, Read, Update, Delete) functionality for departments, with soft deletion support, audit tracking, and a user-friendly interface.

Backend (Django)

Overview

• App Name: academics
• Purpose: Manage academic departments with a RESTful API.
• Location: academics/ directory in the Django project.

Key Components

1. Model: Department (academics/models.py)

   • Fields:
     • id: Auto-generated 4-digit unique identifier (e.g., "1000").
     • name: Department name (max 50 chars, letters/spaces/& only).
     • faculty: Enum-based faculty affiliation (e.g., "I&C" for Information & Computing).
     • Audit fields: created_by, created_at, updated_by, updated_at.
     • is_deleted: Boolean flag for soft deletion (default: False).
   • Features:
     • Custom DepartmentManager for auto-incrementing IDs (1000–9999).
     • Soft deletion via overridden delete() method.
     • Unique constraint on active (is_deleted=False) name and faculty pairs.

2. Serializer: DepartmentSerializer (academics/serializers.py)

   • Handles serialization/deserialization for CRUD operations.
   • Includes FacultyChoiceSerializer for faculty dropdown options.
   • Validates authenticated requests and uses the custom manager for creation.

3. ViewSet: DepartmentViewSet (academics/views.py)

   • Provides RESTful endpoints for department management.
   • Permissions: AllowAny for GET (list/retrieve), IsAuthenticated for POST/PUT/DELETE.
   • Filtering: Supports faculty and is_deleted query params.
   • Soft deletion: Sets is_deleted=True instead of hard delete.
   • Custom queryset: Staff see all departments; others see only active ones (is_deleted=False).

4. URLs: (academics/urls.py)

   • Endpoints:
     • GET /academic/departments/: List departments.
     • GET /academic/departments/<id>/: Retrieve a department.
     • POST /academic/departments/: Create a department (authenticated).
     • PUT /academic/departments/<id>/: Update a department (authenticated).
     • DELETE /academic/departments/<id>/: Soft-delete a department (authenticated).
     • GET /academic/faculty-choices/: List faculty options.

Frontend (Next.js)

Overview

• Page: Departments (src/app/departments/page.js)
• Purpose: Provide a UI to manage departments, integrating with the backend API.
• Location: src/app/departments/ and supporting files in src/.

Key Components

1. Environment: .env.local

   • Configures API endpoints (e.g., NEXT_PUBLIC_ACADEMIC_DEPARTMENTS_PATH=/academic/departments/).
   • Defines base URL (NEXT_PUBLIC_API_URL=http://localhost:8000).

2. API Service: departmentService.js (src/lib/api/)

   • Handles API calls for CRUD operations and faculty choices using apiClient.
   • Methods: getDepartments, getDepartment, createDepartment, updateDepartment, deleteDepartment, getFacultyChoices.

3. State Management: departmentStore.js (src/stores/)

   • Uses Zustand to manage department state (departments, facultyChoices, isLoading, error).
   • Actions: Fetch, create, update, and soft-delete departments, with toast notifications.

4. Components:

   • DynamicForm (src/components/common/DynamicForm.js):
     • Reusable form with support for text, textarea, file, and select inputs.
     • Uses react-hook-form for validation and state management.
     • Pre-populates data for editing and sanitizes inputs.
   • GenericTable (src/components/common/GenericTable.js):
     • Reusable table with sorting, searching, and action buttons (Edit, Delete).
     • Displays department data with clickable names for details.

5. Departments Page (src/app/departments/page.js):

   • Features:
     • Displays a table of active departments (is_deleted=False).
     • Form for creating/updating departments with faculty dropdown.
     • Soft-delete confirmation via toast with "Yes, Delete" and "Cancel" options.
     • Department details in a toast popup.
   • Integration:
     • Fetches departments and faculty choices on mount.
     • Filters out soft-deleted departments from the UI.

Functionality

• Create: Add a new department with a unique name and faculty.
• Read: View all active departments (staff can filter by is_deleted via API).
• Update: Edit department name or faculty, preserving audit trail.
• Delete: Soft-delete departments (sets is_deleted=True), hidden from non-staff UI.

Soft Deletion

• Backend: Marks departments as is_deleted=True instead of removing them.
• Frontend: Filters out soft-deleted departments from the table after deletion.

Setup

1. Backend:
   • Install dependencies: pip install -r requirements.txt.
   • Run migrations: python manage.py migrate.
   • Start server: python manage.py runserver.
2. Frontend:
   • Install dependencies: npm install.
   • Configure .env.local with backend URL.
   • Run dev server: npm run dev.

Notes

• Authentication: Required for create, update, and delete actions.
• API Base Path: /academic/ (configured in university/urls.py).
• Date: Documentation reflects state as of March 25, 2025.

---