# URL Structure Improvements Documentation

## Overview
This document outlines the comprehensive improvements made to the ATS application's URL structure to enhance consistency, maintainability, and scalability.

## Changes Made

### 1. Main Project URLs (`NorahUniversity/urls.py`)

#### API Versioning
- **Before**: `path('api/', include(router.urls))`
- **After**: `path('api/v1/', include(router.urls))`
- **Benefit**: Enables future API versioning without breaking changes

#### API Endpoint Organization
- **Before**:
  - `path('api/templates/', ...)`
  - `path('api/webhook/', ...)`
- **After**:
  - `path('api/v1/templates/', ...)`
  - `path('api/v1/webhooks/zoom/', ...)`
- **Benefit**: Consistent API structure with proper versioning

#### Sync API Organization
- **Before**:
  - `path('sync/task/<str:task_id>/status/', ...)`
  - `path('sync/history/', ...)`
- **After**:
  - `path('api/v1/sync/task/<str:task_id>/status/', ...)`
  - `path('api/v1/sync/history/', ...)`
- **Benefit**: Sync endpoints properly categorized under API

### 2. Application URLs (`recruitment/urls.py`)

#### Application URL Consistency
- **Standardized Pattern**: `applications/<slug:slug>/[action]/`
- **Examples**:
  - `applications/<slug:slug>/` (detail view)
  - `applications/<slug:slug>/update/` (update view)
  - `applications/<slug:slug>/delete/` (delete view)
  - `applications/<slug:slug>/documents/upload/` (document upload)

#### Document Management URLs
- **Before**: Inconsistent patterns
- **After**: Consistent structure
  - `applications/<slug:slug>/documents/upload/`
  - `applications/<slug:slug>/documents/<int:document_id>/delete/`
  - `applications/<slug:slug>/documents/<int:document_id>/download/`

#### Applicant Portal URLs
- **Standardized**: `applications/<slug:slug>/applicant-view/`
- **Benefit**: Clear separation between admin and applicant views

#### Removed Duplicates
- Eliminated duplicate `compose_application_email` URL
- Cleaned up commented-out URLs
- Removed inconsistent URL patterns

## URL Structure Standards

### 1. Naming Conventions
- **Snake Case**: All URL patterns use snake_case
- **Consistent Naming**: Related URLs share common prefixes
- **Descriptive Names**: URL names clearly indicate their purpose

### 2. Parameter Patterns
- **Slugs for SEO**: `<slug:slug>` for user-facing URLs
- **Integers for IDs**: `<int:pk>` or `<int:document_id>` for internal references
- **String Parameters**: `<str:task_id>` for non-numeric identifiers

### 3. RESTful Patterns
- **Collection URLs**: `/resource/` (plural)
- **Resource URLs**: `/resource/<id>/` (singular)
- **Action URLs**: `/resource/<id>/action/`

## API Structure

### Version 1 API Endpoints
```
/api/v1/
├── jobs/                    # JobPosting ViewSet
├── candidates/              # Candidate ViewSet
├── templates/              # Form template management
│   ├── POST save/          # Save template
│   ├── GET <slug>/        # Load template
│   └── DELETE <slug>/     # Delete template
├── webhooks/
│   └── zoom/              # Zoom webhook endpoint
└── sync/
    ├── task/<id>/status/  # Sync task status
    └── history/           # Sync history
```

## Frontend URL Organization

### 1. Core Dashboard & Navigation
```
/                          # Dashboard
/login/                    # Portal login
/careers/                  # Public careers page
```

### 2. Job Management
```
/jobs/
├── <slug>/                           # Job detail
├── create/                           # Create new job
├── <slug>/update/                     # Edit job
├── <slug>/upload-image/               # Upload job image
├── <slug>/applicants/                 # Job applicants list
├── <slug>/applications/               # Job applications list
├── <slug>/calendar/                  # Interview calendar
├── bank/                             # Job bank
├── <slug>/post-to-linkedin/           # Post to LinkedIn
├── <slug>/edit_linkedin_post_content/ # Edit LinkedIn content
├── <slug>/staff-assignment/           # Staff assignment
├── <slug>/sync-hired-applications/    # Sync hired applications
├── <slug>/export/<stage>/csv/         # Export applications CSV
├── <slug>/request-download/           # Request CV download
├── <slug>/download-ready/             # Download ready CVs
├── <slug>/applications_screening_view/     # Screening stage view
├── <slug>/applications_exam_view/          # Exam stage view
├── <slug>/applications_interview_view/     # Interview stage view
├── <slug>/applications_document_review_view/ # Document review view
├── <slug>/applications_offer_view/         # Offer stage view
├── <slug>/applications_hired_view/        # Hired stage view
├── <slug>/application/<app_slug>/update_status/<stage>/<status>/ # Update status
├── <slug>/update_application_exam_status/   # Update exam status
├── <slug>/reschedule_meeting_for_application/ # Reschedule meeting
├── <slug>/schedule-interviews/            # Schedule interviews
├── <slug>/confirm-schedule-interviews/    # Confirm schedule
└── <slug>/applications/compose-email/      # Compose email
```

### 3. Application/Candidate Management
```
/applications/
├── <slug>/                           # Application detail
├── create/                           # Create new application
├── create/<job_slug>/                 # Create for specific job
├── <slug>/update/                     # Update application
├── <slug>/delete/                     # Delete application
├── <slug>/resume-template/             # Resume template view
├── <slug>/update-stage/               # Update application stage
├── <slug>/retry-scoring/              # Retry AI scoring
├── <slug>/applicant-view/             # Applicant portal view
├── <slug>/documents/upload/           # Upload documents
├── <slug>/documents/<doc_id>/delete/  # Delete document
└── <slug>/documents/<doc_id>/download/ # Download document
```

### 4. Interview Management
```
/interviews/
├── <slug>/                           # Interview detail
├── create/<app_slug>/                 # Create interview (type selection)
├── create/<app_slug>/remote/          # Create remote interview
├── create/<app_slug>/onsite/          # Create onsite interview
├── <slug>/update_interview_status      # Update interview status
├── <slug>/cancel_interview_for_application # Cancel interview
└── <job_slug>/get_interview_list      # Get interview list for job
```

### 5. Person/Contact Management
```
/persons/
├── <slug>/    # Person detail
├── create/    # Create person
├── <slug>/update/ # Update person
└── <slug>/delete/ # Delete person
```

### 6. Training Management
```
/training/
├── <slug>/    # Training detail
├── create/    # Create training
├── <slug>/update/ # Update training
└── <slug>/delete/ # Delete training
```

### 7. Form & Template Management
```
/forms/
├── builder/                          # Form builder
├── builder/<template_slug>/           # Form builder for template
├── create-template/                   # Create form template
├── <template_id>/submissions/<slug>/  # Form submission details
├── template/<slug>/submissions/       # Template submissions
└── template/<template_id>/all-submissions/ # All submissions

/application/
├── signup/<template_slug>/            # Application signup
├── <template_slug>/                   # Submit form
├── <template_slug>/submit/            # Submit action
├── <template_slug>/apply/             # Apply action
└── <template_slug>/success/           # Success page
```

### 8. Integration & External Services
```
/integration/erp/
├── /                    # ERP integration view
├── create-job/          # Create job via ERP
├── update-job/          # Update job via ERP
└── health/             # ERP health check

/jobs/linkedin/
├── login/              # LinkedIn login
└── callback/           # LinkedIn callback

/sources/
├── <pk>/               # Source detail
├── create/             # Create source
├── <pk>/update/        # Update source
├── <pk>/delete/        # Delete source
├── <pk>/generate-keys/  # Generate API keys
├── <pk>/toggle-status/  # Toggle source status
├── <pk>/test-connection/ # Test connection
└── api/copy-to-clipboard/ # Copy to clipboard
```

### 9. Agency & Portal Management
```
/agencies/
├── <slug>/                    # Agency detail
├── create/                    # Create agency
├── <slug>/update/             # Update agency
├── <slug>/delete/             # Delete agency
└── <slug>/applications/       # Agency applications

/agency-assignments/
├── <slug>/                    # Assignment detail
├── create/                    # Create assignment
├── <slug>/update/             # Update assignment
└── <slug>/extend-deadline/     # Extend deadline

/agency-access-links/
├── <slug>/                    # Access link detail
├── create/                    # Create access link
├── <slug>/deactivate/          # Deactivate link
└── <slug>/reactivate/          # Reactivate link

/portal/
├── dashboard/                 # Agency portal dashboard
├── logout/                    # Portal logout
├── <pk>/reset/               # Password reset
├── persons/                   # Persons list
├── assignment/<slug>/         # Assignment detail
├── assignment/<slug>/submit-application/ # Submit application
└── submit-application/        # Submit application action

/applicant/
└── dashboard/                 # Applicant portal dashboard

/portal/applications/
├── <app_id>/edit/            # Edit application
└── <app_id>/delete/          # Delete application
```

### 10. User & Account Management
```
/user/
├── <pk>                       # User detail
├── user_profile_image_update/<pk> # Update profile image
└── <pk>/password-reset/        # Password reset

/staff/
└── create                     # Create staff user

/set_staff_password/<pk>/       # Set staff password
/account_toggle_status/<pk>     # Toggle account status
```

### 11. Communication & Messaging
```
/messages/
├── <message_id>/              # Message detail
├── create/                    # Create message
├── <message_id>/reply/        # Reply to message
├── <message_id>/mark-read/     # Mark as read
├── <message_id>/mark-unread/   # Mark as unread
└── <message_id>/delete/       # Delete message
```

### 12. System & Administrative
```
/settings/
├── <pk>/                      # Settings detail
├── create/                    # Create settings
├── <pk>/update/              # Update settings
├── <pk>/delete/              # Delete settings
└── <pk>/toggle/              # Toggle settings

/easy_logs/                   # Easy logs view

/note/
├── <slug>/application_add_note/ # Add application note
├── <slug>/interview_add_note/  # Add interview note
└── <slug>/delete/             # Delete note
```

### 13. Document Management
```
/documents/
├── upload/<slug>/             # Upload document
├── <doc_id>/delete/          # Delete document
└── <doc_id>/download/        # Download document
```

### 14. API Endpoints
```
/api/
├── create/                   # Create job API
├── <slug>/edit/             # Edit job API
├── application/<app_id>/     # Application detail API
├── unread-count/            # Unread count API

/htmx/
├── <pk>/application_criteria_view/    # Application criteria view
├── <slug>/application_set_exam_date/  # Set exam date
└── <slug>/application_update_status/  # Update status
```

## Benefits of Improvements

### 1. Maintainability
- **Consistent Patterns**: Easier to understand and modify
- **Clear Organization**: Related URLs grouped together
- **Reduced Duplication**: Eliminated redundant URL definitions

### 2. Scalability
- **API Versioning**: Ready for future API changes
- **Modular Structure**: Easy to add new endpoints
- **RESTful Design**: Follows industry standards

### 3. Developer Experience
- **Predictable URLs**: Easy to guess URL patterns
- **Clear Naming**: URL names indicate their purpose
- **Better Documentation**: Structure is self-documenting

### 4. SEO and User Experience
- **Clean URLs**: User-friendly and SEO-optimized
- **Consistent Patterns**: Users can navigate intuitively
- **Clear Separation**: Admin vs. user-facing URLs

## Migration Guide

### For Developers
1. **Update API Calls**: Change `/api/` to `/api/v1/`
2. **Update Sync URLs**: Move sync endpoints to `/api/v1/sync/`
3. **Update Template References**: Use new URL names in templates

### For Frontend Code
1. **JavaScript Updates**: Update AJAX calls to use new API endpoints
2. **Template Updates**: Use new URL patterns in Django templates
3. **Form Actions**: Update form actions to use new URLs

## Future Considerations

### 1. API v2 Planning
- Structure is ready for API v2 implementation
- Can maintain backward compatibility with v1

### 2. Additional Endpoints
- Easy to add new endpoints following established patterns
- Consistent structure makes expansion straightforward

### 3. Authentication
- API structure ready for token-based authentication
- Clear separation of public and private endpoints

## Testing Recommendations

### 1. URL Resolution Tests
- Test all new URL patterns resolve correctly
- Verify reverse URL lookups work

### 2. API Endpoint Tests
- Test API v1 endpoints respond correctly
- Verify versioning doesn't break existing functionality

### 3. Integration Tests
- Test frontend templates with new URLs
- Verify JavaScript AJAX calls work with new endpoints

## Conclusion

These URL structure improvements provide a solid foundation for the ATS application's continued development and maintenance. The consistent, well-organized structure will make future enhancements easier and improve the overall developer experience.